Share via

@azure/identity package

  • Reference

Classes

AggregateAuthenticationError

Provides an errors array containing AuthenticationError instance for authentication failures from credentials in a ChainedTokenCredential.
AuthenticationError

Provides details about a failure to authenticate with Azure Active Directory. The errorResponse field contains more details about the specific failure.
AuthenticationRequiredError

Error used to enforce authentication after trying to retrieve a token silently.
AuthorizationCodeCredential

Enables authentication to Microsoft Entra ID using an authorization code that was obtained through the authorization code flow, described in more detail in the Microsoft Entra ID documentation:

https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow
AzureCliCredential

This credential will use the currently logged-in user login information via the Azure CLI ('az') commandline tool. To do so, it will read the user access token and expire time with Azure CLI command "az account get-access-token".
AzureDeveloperCliCredential

Azure Developer CLI is a command-line interface tool that allows developers to create, manage, and deploy resources in Azure. It's built on top of the Azure CLI and provides additional functionality specific to Azure developers. It allows users to authenticate as a user and/or a service principal against Microsoft Entra ID. The AzureDeveloperCliCredential authenticates in a development environment and acquires a token on behalf of the logged-in user or service principal in the Azure Developer CLI. It acts as the Azure Developer CLI logged in user or service principal and executes an Azure CLI command underneath to authenticate the application against Microsoft Entra ID.

Configure AzureDeveloperCliCredential

To use this credential, the developer needs to authenticate locally in Azure Developer CLI using one of the commands below:

  1. Run "azd auth login" in Azure Developer CLI to authenticate interactively as a user.
  2. Run "azd auth login --client-id clientID --client-secret clientSecret --tenant-id tenantID" to authenticate as a service principal.

You may need to repeat this process after a certain time period, depending on the refresh token validity in your organization. Generally, the refresh token validity period is a few weeks to a few months. AzureDeveloperCliCredential will prompt you to sign in again.
AzurePipelinesCredential

This credential is designed to be used in Azure Pipelines with service connections as a setup for workload identity federation.
AzurePowerShellCredential

This credential will use the currently logged-in user information from the Azure PowerShell module. To do so, it will read the user access token and expire time with Azure PowerShell command Get-AzAccessToken -ResourceUrl {ResourceScope}
ChainedTokenCredential

Enables multiple TokenCredential implementations to be tried in order until one of the getToken methods returns an access token.
ClientAssertionCredential

Authenticates a service principal with a JWT assertion.
ClientCertificateCredential

Enables authentication to Microsoft Entra ID using a PEM-encoded certificate that is assigned to an App Registration. More information on how to configure certificate authentication can be found here:

https://learn.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad
ClientSecretCredential

Enables authentication to Microsoft Entra ID using a client secret that was generated for an App Registration. More information on how to configure a client secret can be found here:

https://learn.microsoft.com/entra/identity-platform/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application
CredentialUnavailableError

This signifies that the credential that was tried in a chained credential was not available to be used as the credential. Rather than treating this as an error that should halt the chain, it's caught and the chain continues
DefaultAzureCredential

Provides a default ChainedTokenCredential configuration that should work for most applications that use the Azure SDK.
DeviceCodeCredential

Enables authentication to Microsoft Entra ID using a device code that the user can enter into https://microsoft.com/devicelogin.
EnvironmentCredential

Enables authentication to Microsoft Entra ID using a client secret or certificate, or as a user with a username and password.
InteractiveBrowserCredential

Enables authentication to Microsoft Entra ID inside of the web browser using the interactive login flow.
ManagedIdentityCredential

Attempts authentication using a managed identity available at the deployment environment. This authentication type works in Azure VMs, App Service instances, Azure Functions applications, Azure Kubernetes Services, Azure Service Fabric instances and inside of the Azure Cloud Shell.

More information about configuring managed identities can be found here: https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview
OnBehalfOfCredential

Enables authentication to Microsoft Entra ID using the On Behalf Of flow.
UsernamePasswordCredential

Enables authentication to Microsoft Entra ID with a user's username and password. This credential requires a high degree of trust so you should only use it when other, more secure credential types can't be used.
VisualStudioCodeCredential

Connects to Azure using the credential provided by the VSCode extension 'Azure Account'. Once the user has logged in via the extension, this credential can share the same refresh token that is cached by the extension.

It's a known issue that this credential doesn't work with Azure Account extension versions newer than 0.9.11. A long-term fix to this problem is in progress. In the meantime, consider authenticating with AzureCliCredential.
WorkloadIdentityCredential

Workload Identity authentication is a feature in Azure that allows applications running on virtual machines (VMs) to access other Azure resources without the need for a service principal or managed identity. With Workload Identity authentication, applications authenticate themselves using their own identity, rather than using a shared service principal or managed identity. Under the hood, Workload Identity authentication uses the concept of Service Account Credentials (SACs), which are automatically created by Azure and stored securely in the VM. By using Workload Identity authentication, you can avoid the need to manage and rotate service principals or managed identities for each application on each VM. Additionally, because SACs are created automatically and managed by Azure, you don't need to worry about storing and securing sensitive credentials themselves. The WorkloadIdentityCredential supports Microsoft Entra Workload ID authentication on Azure Kubernetes and acquires a token using the SACs available in the Azure Kubernetes environment. Refer to Microsoft Entra Workload ID for more information.

Interfaces

AccessToken

Represents an access token with an expiration time.
AuthenticationRecord

The record to use to find the cached tokens in the cache.
AuthenticationRequiredErrorOptions

Optional parameters to the AuthenticationRequiredError
AuthorityValidationOptions

Provides options to configure how the Identity library does authority validation during authentication requests to Microsoft Entra ID.
AuthorizationCodeCredentialOptions

Options for the AuthorizationCodeCredential
AzureCliCredentialOptions

Options for the AzureCliCredential
AzureDeveloperCliCredentialOptions

Options for the AzureDeveloperCliCredential
AzurePipelinesCredentialOptions

Optional parameters for the AzurePipelinesCredential class.
AzurePowerShellCredentialOptions

Options for the AzurePowerShellCredential
BrokerAuthOptions

Configuration options for InteractiveBrowserCredential to support WAM Broker Authentication.
BrokerDisabledOptions

Parameters when WAM broker authentication is disabled.
BrokerEnabledOptions

Parameters when WAM broker authentication is enabled.
BrowserCustomizationOptions

Shared configuration options for browser customization
ClientAssertionCredentialOptions

Options for the ClientAssertionCredential
ClientCertificateCredentialOptions

Optional parameters for the ClientCertificateCredential class.
ClientCertificatePEMCertificate

Required configuration options for the ClientCertificateCredential, with the string contents of a PEM certificate
ClientCertificatePEMCertificatePath

Required configuration options for the ClientCertificateCredential, with the path to a PEM certificate.
ClientSecretCredentialOptions

Optional parameters for the ClientSecretCredential class.
CredentialPersistenceOptions

Shared configuration options for credentials that support persistent token caching.
DefaultAzureCredentialClientIdOptions

Provides options to configure the DefaultAzureCredential class. This variation supports managedIdentityClientId and not managedIdentityResourceId, since only one of both is supported.
DefaultAzureCredentialOptions

Provides options to configure the DefaultAzureCredential class.
DefaultAzureCredentialResourceIdOptions

Provides options to configure the DefaultAzureCredential class. This variation supports managedIdentityResourceId and not managedIdentityClientId, since only one of both is supported.
DeviceCodeCredentialOptions

Defines options for the InteractiveBrowserCredential class for Node.js.
DeviceCodeInfo

Provides the user code and verification URI where the code must be entered. Also provides a message to display to the user which contains an instruction with these details.
EnvironmentCredentialOptions

Enables authentication to Microsoft Entra ID depending on the available environment variables. Defines options for the EnvironmentCredential class.
ErrorResponse

See the official documentation for more details:

https://learn.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code#error-response-1

NOTE: This documentation is for v1 OAuth support but the same error response details still apply to v2.
GetBearerTokenProviderOptions

The options to configure the token provider.
GetTokenOptions

Defines options for TokenCredential.getToken.
InteractiveBrowserCredentialInBrowserOptions

Defines the common options for the InteractiveBrowserCredential class.
InteractiveBrowserCredentialNodeOptions

Defines the common options for the InteractiveBrowserCredential class.
InteractiveCredentialOptions

Common constructor options for the Identity credentials that requires user interaction.
ManagedIdentityCredentialClientIdOptions

Options to send on the ManagedIdentityCredential constructor. This variation supports clientId and not resourceId, since only one of both is supported.
ManagedIdentityCredentialResourceIdOptions

Options to send on the ManagedIdentityCredential constructor. This variation supports resourceId and not clientId, since only one of both is supported.
MultiTenantTokenCredentialOptions

Options for multi-tenant applications which allows for additionally allowed tenants.
OnBehalfOfCredentialAssertionOptions

Defines the parameters to authenticate the OnBehalfOfCredential with an assertion.
OnBehalfOfCredentialCertificateOptions

Defines the parameters to authenticate the OnBehalfOfCredential with a certificate.
OnBehalfOfCredentialSecretOptions

Defines the parameters to authenticate the OnBehalfOfCredential with a secret.
TokenCachePersistenceOptions

Parameters that enable token cache persistence in the Identity credentials.
TokenCredential

Represents a credential capable of providing an authentication token.
TokenCredentialOptions

Provides options to configure how the Identity library makes authentication requests to Microsoft Entra ID.
UsernamePasswordCredentialOptions

Defines options for the UsernamePasswordCredential class.
VisualStudioCodeCredentialOptions

Provides options to configure the Visual Studio Code credential.
WorkloadIdentityCredentialOptions

Options for the WorkloadIdentityCredential

Type Aliases

BrokerOptions

Parameters that enable WAM broker authentication in the InteractiveBrowserCredential.
BrowserLoginStyle

(Browser-only feature) The "login style" to use in the authentication flow:

  • "redirect" redirects the user to the authentication page and then redirects them back to the page once authentication is completed.
  • "popup" opens a new browser window through with the redirect flow is initiated. The user's existing browser window does not leave the current page
ClientCertificateCredentialPEMConfiguration

Required configuration options for the ClientCertificateCredential, with either the string contents of a PEM certificate, or the path to a PEM certificate.
DeviceCodePromptCallback

Defines the signature of a callback which will be passed to DeviceCodeCredential for the purpose of displaying authentication details to the user.
IdentityPlugin

The type of an Azure Identity plugin, a function accepting a plugin context.
OnBehalfOfCredentialOptions

Optional parameters for the OnBehalfOfCredential class.

Enums

AzureAuthorityHosts

A list of known Azure authority hosts

Functions

deserializeAuthenticationRecord(string)

Deserializes a previously serialized authentication record from a string into an object.

The input string must contain the following properties:

  • "authority"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

If the version we receive is unsupported, an error will be thrown.

At the moment, the only available version is: "1.0", which is always set when the authentication record is serialized.
getBearerTokenProvider(TokenCredential, string | string[], GetBearerTokenProviderOptions)

Returns a callback that provides a bearer token. For example, the bearer token can be used to authenticate a request as follows:

import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const getAccessToken = getBearerTokenProvider(credential, scope);
const token = await getAccessToken();

// usage
const request = createPipelineRequest({ url: "https://example.com" });
request.headers.set("Authorization", `Bearer ${token}`);
getDefaultAzureCredential()

Returns a new instance of the DefaultAzureCredential.
serializeAuthenticationRecord(AuthenticationRecord)

Serializes an AuthenticationRecord into a string.

The output of a serialized authentication record will contain the following properties:

  • "authority"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

To later convert this string to a serialized AuthenticationRecord, please use the exported function deserializeAuthenticationRecord().
useIdentityPlugin(IdentityPlugin)

Extend Azure Identity with additional functionality. Pass a plugin from a plugin package, such as:

  • @azure/identity-cache-persistence: provides persistent token caching
  • @azure/identity-vscode: provides the dependencies of VisualStudioCodeCredential and enables it

Example:

import { cachePersistencePlugin } from "@azure/identity-cache-persistence";

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
useIdentityPlugin(cachePersistencePlugin);

// The plugin has the capability to extend `DefaultAzureCredential` and to
// add middleware to the underlying credentials, such as persistence.
const credential = new DefaultAzureCredential({
  tokenCachePersistenceOptions: {
    enabled: true
  }
});

Function Details

deserializeAuthenticationRecord(string)

Deserializes a previously serialized authentication record from a string into an object.

The input string must contain the following properties:

  • "authority"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

If the version we receive is unsupported, an error will be thrown.

At the moment, the only available version is: "1.0", which is always set when the authentication record is serialized.

function deserializeAuthenticationRecord(serializedRecord: string): AuthenticationRecord

Parameters

serializedRecord

string

Authentication record previously serialized into string.

Returns

AuthenticationRecord

AuthenticationRecord.

getBearerTokenProvider(TokenCredential, string | string[], GetBearerTokenProviderOptions)

Returns a callback that provides a bearer token. For example, the bearer token can be used to authenticate a request as follows:

import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const getAccessToken = getBearerTokenProvider(credential, scope);
const token = await getAccessToken();

// usage
const request = createPipelineRequest({ url: "https://example.com" });
request.headers.set("Authorization", `Bearer ${token}`);

function getBearerTokenProvider(credential: TokenCredential, scopes: string | string[], options?: GetBearerTokenProviderOptions): () => Promise<string>

Parameters

credential
TokenCredential

The credential used to authenticate the request.

scopes

string | string[]

The scopes required for the bearer token.

options
GetBearerTokenProviderOptions

Options to configure the token provider.

Returns

() => Promise<string>

a callback that provides a bearer token.

getDefaultAzureCredential()

Returns a new instance of the DefaultAzureCredential.

function getDefaultAzureCredential(): TokenCredential

Returns

TokenCredential

serializeAuthenticationRecord(AuthenticationRecord)

Serializes an AuthenticationRecord into a string.

The output of a serialized authentication record will contain the following properties:

  • "authority"
  • "homeAccountId"
  • "clientId"
  • "tenantId"
  • "username"
  • "version"

To later convert this string to a serialized AuthenticationRecord, please use the exported function deserializeAuthenticationRecord().

function serializeAuthenticationRecord(record: AuthenticationRecord): string

Parameters

record
AuthenticationRecord

Returns

string

useIdentityPlugin(IdentityPlugin)

Extend Azure Identity with additional functionality. Pass a plugin from a plugin package, such as:

  • @azure/identity-cache-persistence: provides persistent token caching
  • @azure/identity-vscode: provides the dependencies of VisualStudioCodeCredential and enables it

Example:

import { cachePersistencePlugin } from "@azure/identity-cache-persistence";

import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
useIdentityPlugin(cachePersistencePlugin);

// The plugin has the capability to extend `DefaultAzureCredential` and to
// add middleware to the underlying credentials, such as persistence.
const credential = new DefaultAzureCredential({
  tokenCachePersistenceOptions: {
    enabled: true
  }
});

function useIdentityPlugin(plugin: IdentityPlugin)

Parameters

plugin
IdentityPlugin

the plugin to register