Credential chains in the Azure Identity library for Java

The Azure Identity library provides credentials—public classes that implement the Azure Core library's TokenCredential interface. A credential represents a distinct authentication flow for acquiring an access token from Microsoft Entra ID. These credentials can be chained together to form an ordered sequence of authentication mechanisms to be attempted.

How a chained credential works

At runtime, a credential chain attempts to authenticate using the sequence's first credential. If that credential fails to acquire an access token, the next credential in the sequence is attempted, and so on, until an access token is successfully obtained. The following sequence diagram illustrates this behavior:

Why use credential chains

A chained credential can offer the following benefits:

• Environment awareness: Automatically selects the most appropriate credential based on the environment in which the app is running. Without it, you'd have to write code like this:

  import com.azure.core.credential.TokenCredential;
  import com.azure.identity.AzureCliCredentialBuilder;
  import com.azure.identity.ManagedIdentityCredentialBuilder;
  
  // Code omitted for brevity
  
  TokenCredential credential = null;
  
  // Set up credential based on environment (Azure or local development)
  String environment = System.getenv("ENV");
  
  if (environment != null && environment.equals("production")) {
      credential = new ManagedIdentityCredentialBuilder()
          .clientId(userAssignedClientId)
          .build();
  } else {
      credential = new AzureCliCredentialBuilder()
          .build();
  }
  

• Seamless transitions: Your app can move from local development to your staging or production environment without changing authentication code.

• Improved resiliency: Includes a fallback mechanism that moves to the next credential when the prior fails to acquire an access token.

How to choose a chained credential

There are two different approaches to credential chaining:

• Use a preconfigured chain: Start with an opinionated, preconstructed chain that accommodates the most common authentication scenarios. For this approach, see the DefaultAzureCredential overview section.
• "Build up" a chain: Start with an empty chain and include only what you need. For this approach, see the ChainedTokenCredential overview section.

DefaultAzureCredential overview

DefaultAzureCredential is an opinionated, preconfigured chain of credentials. It's designed to support many environments, along with the most common authentication flows and developer tools. In graphical form, the underlying chain looks like this:

The order in which DefaultAzureCredential attempts credentials follows.

Order	Credential	Description
1	Environment	Reads a collection of environment variables to determine if an application service principal (application user) is configured for the app. If so, DefaultAzureCredential uses these values to authenticate the app to Azure. This method can be used when developing locally, but is most often used in server environments.
2	Workload Identity	If the app is deployed to an Azure host with Workload Identity enabled, authenticate that account.
3	Managed Identity	If the app is deployed to an Azure host with Managed Identity enabled, authenticate the app to Azure using that Managed Identity.
4	IntelliJ	If the developer authenticated via Azure Toolkit for IntelliJ, authenticate that account.
5	Visual Studio Code	If the developer authenticated via Visual Studio Code's Azure Resources extension and the azure-identity-broker package is installed, authenticate that account.
6	Azure CLI	If the developer authenticated to Azure using Azure CLI's az login command, authenticate the app to Azure using that same account.
7	Azure PowerShell	If the developer authenticated to Azure using Azure PowerShell's Connect-AzAccount cmdlet, authenticate the app to Azure using that same account.
8	Azure Developer CLI	If the developer authenticated to Azure using Azure Developer CLI's azd auth login command, authenticate with that account.
9	Broker	Authenticates using the default account logged into the OS via a broker. Requires that the azure-identity-broker package is installed, since a broker-enabled instance of InteractiveBrowserCredential is used.

In its simplest form, you can use the parameterless version of DefaultAzureCredential as follows:

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

How to customize DefaultAzureCredential

The following sections describe strategies for controlling which credentials are included in the chain.

Exclude a credential type category

To exclude all Developer tool or Deployed service credentials, set environment variable AZURE_TOKEN_CREDENTIALS to prod or dev, respectively. When a value of prod is used, the underlying credential chain looks as follows:

When a value of dev is used, the chain looks as follows:

Important

The AZURE_TOKEN_CREDENTIALS environment variable is supported in azure-identity package versions 1.16.1 and later.

To ensure the environment variable is defined and set to a supported string, call method requireEnvVars as follows:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Important

The requireEnvVars method is available in azure-identity package versions 1.18.0 and later.

To use a custom environment variable name instead of the default AZURE_TOKEN_CREDENTIALS, use AzureIdentityEnvVars.fromString() to create a reference to your custom variable:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Note

The requireEnvVars method throws an IllegalStateException if the specified environment variables aren't set or are empty.

Use a specific credential

To exclude all credentials except for one, set environment variable AZURE_TOKEN_CREDENTIALS to the credential name. For example, you can reduce the DefaultAzureCredential chain to AzureCliCredential by setting AZURE_TOKEN_CREDENTIALS to AzureCliCredential. The string comparison is performed in a case-insensitive manner. Valid string values for the environment variable include:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Important

The AZURE_TOKEN_CREDENTIALS environment variable supports individual credential names in azure-identity package versions 1.17.0 and later.

To ensure the environment variable is defined and set to a supported string, call method requireEnvVars as follows:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

ChainedTokenCredential overview

ChainedTokenCredential is an empty chain to which you add credentials to suit your app's needs. For example:

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

The preceding code example creates a tailored credential chain comprised of two development-time credentials. AzureCliCredential is attempted first, followed by IntelliJCredential, if necessary. In graphical form, the chain looks like this:

Tip

For improved performance, optimize credential ordering in ChainedTokenCredential from most to least used credential.

Usage guidance for DefaultAzureCredential

DefaultAzureCredential is undoubtedly the easiest way to get started with the Azure Identity library, but with that convenience comes tradeoffs. After you deploy your app to Azure, you should understand the app's authentication requirements and consider whether DefaultAzureCredential is appropriate for your scenario.

DefaultAzureCredential offers a key benefit: it decouples your application code from specific authentication mechanisms, enabling you to change your authentication configuration without modifying code. For experienced developers who consciously configure their production authentication, this flexibility can be valuable. However, this flexibility comes with potential drawbacks:

• Debugging challenges: When authentication fails, it can be challenging to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success/failure status of each. For more information, see Debug a chained credential.
• Performance overhead: The process of sequentially trying multiple credentials can introduce performance overhead. For example, when running on a local development machine, managed identity is unavailable. Consequently, ManagedIdentityCredential always fails in the local development environment.
• Unpredictable behavior: DefaultAzureCredential checks for the presence of certain environment variables. It's possible that someone could add or modify these environment variables at the system level on the host machine. Those changes apply globally and therefore alter the behavior of DefaultAzureCredential at runtime in any app running on that machine.
• Permission mismatches: DefaultAzureCredential stops at the first credential that successfully acquires a token, regardless of whether that credential has the correct permissions. For example, a local development credential might have broader permissions than the production managed identity, causing the app to work locally but fail authorization checks after deployment.

Debug a chained credential

To diagnose an unexpected issue or to understand what a chained credential is doing, enable logging in your app.

For illustration purposes, assume the parameterless form of DefaultAzureCredential is used to authenticate a request to a Blob Storage account. The app runs in the local development environment, and the developer authenticated to Azure using the Azure CLI. When the app is run, the following pertinent entries appear in the output:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

In the preceding output, notice that:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential, and VisualStudioCodeCredential each failed to acquire a Microsoft Entra access token, in that order.
• The AzureCliCredential.getToken call succeeds, as indicated by the returns a token-suffixed entry. Since AzureCliCredential succeeded, no credentials beyond it were tried.