Edit

Share via

Credential chains in the Azure Identity library for .NET

  • Article

The Azure Identity library provides credentials—public classes derived from the Azure Core library's TokenCredential class. 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:

Credential chain sequence diagram

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:

    C# 
    TokenCredential credential;

if (app.Environment.IsProduction() || app.Environment.IsStaging())
{
    credential = new ManagedIdentityCredential(
        ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
}
else
{
    // local development environment
    credential = new VisualStudioCredential();
}

  • 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 disparate philosophies to credential chaining:

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:

DefaultAzureCredential auth flowchart

The order in which DefaultAzureCredential attempts credentials follows.

Order Credential Description Enabled by default?
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 is most often used in server environments but can also be used when developing locally. Yes
2 Workload Identity If the app is deployed to an Azure host with Workload Identity enabled, authenticate that account. Yes
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. Yes
4 Visual Studio If the developer authenticated to Azure by logging into Visual Studio, authenticate the app to Azure using that same account. Yes
5 Azure CLI If the developer authenticated to Azure using Azure CLI's az login command, authenticate the app to Azure using that same account. Yes
6 Azure PowerShell If the developer authenticated to Azure using Azure PowerShell's Connect-AzAccount cmdlet, authenticate the app to Azure using that same account. Yes
7 Azure Developer CLI If the developer authenticated to Azure using Azure Developer CLI's azd auth login command, authenticate with that account. Yes
8 Interactive browser If enabled, interactively authenticate the developer via the current system's default browser. No

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

C# 
builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Tip

The UseCredential method in the preceding code snippet is recommended for use in ASP.NET Core apps. For more information, see Use the Azure SDK for .NET in ASP.NET Core apps.

How to customize DefaultAzureCredential

To remove a credential from DefaultAzureCredential, use the corresponding Exclude-prefixed property in DefaultAzureCredentialOptions. For example:

C# 
builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

In the preceding code sample, EnvironmentCredential, ManagedIdentityCredential, and WorkloadIdentityCredential are removed from the credential chain. As a result, the first credential to be attempted is VisualStudioCredential. The modified chain contains only development-time credentials and looks like this:

DefaultAzureCredential using Excludes properties

Note

InteractiveBrowserCredential is excluded by default and therefore isn't shown in the preceding diagram. To include InteractiveBrowserCredential, either pass true to constructor DefaultAzureCredential(Boolean) or set property DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential to false.

As more Exclude-prefixed properties are set to true (credential exclusions are configured), the advantages of using DefaultAzureCredential diminish. In such cases, ChainedTokenCredential is a better choice and requires less code. To illustrate, these two code samples behave the same way:

C# 
credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
    });

ChainedTokenCredential overview

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

C# 
builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

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

ChainedTokenCredential

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. Once you deploy your app to Azure, you should understand the app's authentication requirements. For that reason, replace DefaultAzureCredential with a specific TokenCredential implementation, such as ManagedIdentityCredential. See the Derived list for options.

Here's why:

  • 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, unless explicitly disabled via its corresponding Exclude-prefixed property.
  • 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. For more information on unpredictability, see Use deterministic credentials in production environments.

Debug a chained credential

To diagnose an unexpected issue or to understand what a chained credential is doing, enable logging in your app. Optionally, filter the logs to only those events emitted from the Azure Identity library. For example:

C# 
using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

For illustration purposes, assume the parameterless form of DefaultAzureCredential was used to authenticate a request to a Log Analytics workspace. The app ran in the local development environment, and Visual Studio was authenticated to an Azure account. The next time the app ran, the following pertinent entries appeared in the output:

Output 
DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

In the preceding output, notice that:

  • EnvironmentCredential, WorkloadIdentityCredential, and ManagedIdentityCredential each failed to acquire a Microsoft Entra access token, in that order.
  • The DefaultAzureCredential credential selected:-prefixed entry indicates the credential that was selected—VisualStudioCredential in this case. Since VisualStudioCredential succeeded, no credentials beyond it were used.