@azure/identity

Azure Identity client library for JS

This library simplifies authentication against Azure Active Directory for Azure SDK libraries. It provides a set of TokenCredential implementations which can be passed into SDK libraries to authenticate API requests. It supports token authentication using an Azure Active Directory service principal or managed identity.

Getting started

Prerequisites

• an Azure subscription
  • if you don't have one, you can sign up for a free account
• Node.js 8 LTS or higher

Install the package

Install Azure Identity with npm:

npm install --save @azure/identity

Key concepts

If this is your first time using @azure/identity or the Microsoft identity platform (Azure Active Directory), we recommend that you read Using @azure/identity with Microsoft Identity Platform first. This document will give you a deeper understanding of the platform and how to configure your Azure account correctly.

Credentials

Azure Identity offers a variety of credential classes that are accepted by Azure SDK data plane clients. Each client library documents its Azure Identity integration in its README and samples. Azure SDK management plane libraries (those starting with @azure/arm-*) do not accept these credentials.

Credentials differ mostly in configuration:

credential class	identity	configuration
DefaultAzureCredential	service principal or managed identity	none for managed identity; environment variables for service principal
ManagedIdentityCredential	managed identity	none
EnvironmentCredential	service principal	environment variables
ClientSecretCredential	service principal	constructor parameters
ClientCertificateCredential	service principal	constructor parameters
DeviceCodeCredential	app registration details	constructor parameters
AuthorizationCodeCredential	app registration details	constructor parameters
InteractiveBrowserCredential	app registration details	constructor parameters
UsernamePasswordCredential	user principal	constructor parameters

Credentials can be chained and tried in turn until one succeeds; see chaining credentials for details.

DefaultAzureCredential

DefaultAzureCredential is appropriate for most scenarios. It supports authenticating as a service principal or managed identity. To authenticate as a service principal, provide configuration in environment variables as described in the next section. Currently this credential attempts to use the EnvironmentCredential and ManagedIdentityCredential, in that order.

Authenticating as a managed identity requires no configuration, but does require platform support. See the managed identity documentation for more information.

Environment variables

DefaultAzureCredential and EnvironmentCredential are configured for service principal authentication with these environment variables:

variable name	value
AZURE_CLIENT_ID	service principal's app id
AZURE_TENANT_ID	id of the principal's Azure Active Directory tenant
AZURE_CLIENT_SECRET	one of the service principal's client secrets (implies ClientSecretCredential)
AZURE_CLIENT_CERTIFICATE_PATH	one of the service principal's client secrets (implies ClientCertificateCredential)
AZURE_USERNAME	the username of a user in the tenant (implies UsernamePasswordCredential)
AZURE_PASSWORD	the password of the user specified in AZURE_USERNAME

Examples

DefaultAzureCredential

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.
const { KeyClient } = require("@azure/keyvault-keys");
const { DefaultAzureCredential } = require("@azure/identity");

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
const client = new KeyClient(vaultUrl, credential);
const getResult = await client.getKey("MyKeyName");

Authenticating as a service principal

// Using a client secret
const { ClientSecretCredential } = require("@azure/identity");
const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

// Using a PEM-encoded certificate with a private key, not password protected
const { ClientCertificateCredential } = require("@azure/identity");
const credential = new ClientCertificateCredential(
  tenantId,
  clientId,
  "/app/certs/certificate.pem"
);

// Using environment variables (see "Environment variables" above for variable names)
const { EnvironmentCredential } = require("@azure/identity");
const credential = new EnvironmentCredential();

Using the AuthorizationCodeCredential

The AuthorizationCodeCredential takes more up-front work to use than the other credential types at this time. A full sample demonstrating how to use this credential can be found in samples/authorizationCodeSample.ts.

Chaining credentials

const { ClientSecretCredential, ChainedTokenCredential } = require("@azure/identity");

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
const { KeysClient } = require("@azure/keyvault-keys");
const client = new KeysClient(vaultUrl, credentialChain);

Troubleshooting

General

Credentials raise AuthenticationError when they fail to authenticate. This class has a message field which describes why authentication failed. An AggregateAuthenticationError will be raised by ChainedTokenCredential with an errors field containing an array of errors from each credential in the chain.

Next steps

Read the documentation

API documentation for this library can be found on our documentation site.

Provide Feedback

If you encounter bugs or have suggestions, please open an issue.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.