Azure.Identity 1.21.0

Azure Identity client library for .NET

The Azure Identity library provides Microsoft Entra ID token-based authentication support across the Azure SDK. It provides a set of TokenCredential implementations that can be used to construct Azure SDK clients that support Microsoft Entra token authentication.

Source code | Package (NuGet) | API reference documentation | Microsoft Entra ID documentation

Getting started

Install the package

Install the Azure Identity client library for .NET with NuGet:

dotnet add package Azure.Identity

Prerequisites

• An Azure subscription.
• The Azure CLI can also be useful for authenticating in a development environment, creating accounts, and managing account roles.

Authenticate the client

When debugging and executing code locally, it's typical for a developer to use their own account for authenticating calls to Azure services. There are several developer tools that can be used to perform this authentication in your development environment. For more information, see Authentication during local development.

Key concepts

Credentials

A credential is a class that contains or can obtain the data needed for a service client to authenticate requests. Service clients across the Azure SDK accept credentials when they're constructed. Service clients use those credentials to authenticate requests to the service.

The Azure Identity library focuses on OAuth authentication with Microsoft Entra ID. It offers numerous credentials capable of acquiring a Microsoft Entra token to authenticate service requests. Each credential in this library is an implementation of the TokenCredential abstract class in Azure.Core, and any of them can be used to construct service clients capable of authenticating with a TokenCredential.

See Credential classes for a complete listing of available credential types.

DefaultAzureCredential

DefaultAzureCredential simplifies authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development. For more information, see DefaultAzureCredential overview.

Continuation policy

As of version 1.10.1, DefaultAzureCredential attempts to authenticate with all developer tool credentials until one succeeds, regardless of any errors previous developer tool credentials experienced. For example, a developer tool credential may attempt to get a token and fail, so DefaultAzureCredential will continue to the next credential in the flow. Deployed service credentials stop the flow with a thrown exception if they're able to attempt token retrieval but don't receive one. Prior to version 1.10.1, developer tool credentials would similarly stop the authentication flow if token retrieval failed.

This behavior allows for trying all of the developer tool credentials on your machine while having predictable deployed behavior.

Examples

Specify a user-assigned managed identity with DefaultAzureCredential

Many Azure hosts allow the assignment of a user-assigned managed identity. The following examples demonstrate configuring DefaultAzureCredential to authenticate a user-assigned managed identity when deployed to an Azure host. The sample code uses the credential to authenticate a BlobClient from the Azure.Storage.Blobs client library. It also demonstrates how you can specify a user-assigned managed identity either by a client ID or a resource ID.

Client ID

To use a client ID, take one of the following approaches:

1. Set the DefaultAzureCredentialOptions.ManagedIdentityClientId property. For example:

// When deployed to an Azure host, DefaultAzureCredential will authenticate the specified user-assigned managed identity.

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var blobClient = new BlobClient(
    new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"),
    credential);

2. Set the AZURE_CLIENT_ID environment variable.

Resource ID

To use a resource ID, set the DefaultAzureCredentialOptions.ManagedIdentityResourceId property. The resource ID takes the form /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}. Because resource IDs can be built by convention, they can be more convenient when there are a large number of user-assigned managed identities in your environment. For example:

string userAssignedResourceId = "<your managed identity resource ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityResourceId = new ResourceIdentifier(userAssignedResourceId)
    });

var blobClient = new BlobClient(
    new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"),
    credential);

Define a custom authentication flow with ChainedTokenCredential

While DefaultAzureCredential is generally the quickest way to authenticate apps for Azure, you can create a customized chain of credentials to be considered. ChainedTokenCredential enables users to combine multiple credential instances to define a customized chain of credentials. For more information, see ChainedTokenCredential overview.

Managed identity support

Managed identity authentication is supported either indirectly via DefaultAzureCredential or directly via ManagedIdentityCredential for the following Azure services:

• Azure App Service and Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Azure Virtual Machines Scale Sets

As of version 1.8.0, ManagedIdentityCredential supports token caching.

Identity binding mode (WorkloadIdentityCredential)

WorkloadIdentityCredential supports an opt-in identity binding mode to work around Entra ID's limit on federated identity credentials (FICs) per managed identity. When enabled via the IsAzureProxyEnabled option, the credential redirects token requests to an AKS-provided proxy that handles the FIC exchange centrally, allowing multiple pods to share the same identity without hitting FIC limits.

Note: This feature is only available when using WorkloadIdentityCredential directly. It is not supported by DefaultAzureCredential or ManagedIdentityCredential.

Usage

var credential = new WorkloadIdentityCredential(new WorkloadIdentityCredentialOptions
{
    IsAzureProxyEnabled = true  // Enable identity binding mode
});

When enabled, the credential reads these environment variables (typically configured by AKS):

• AZURE_KUBERNETES_TOKEN_PROXY - Base HTTPS URL for the proxy endpoint
• AZURE_KUBERNETES_CA_FILE - Path to PEM bundle with proxy CA certificates
• AZURE_KUBERNETES_CA_DATA - PEM-encoded CA bundle (mutually exclusive with AZURE_KUBERNETES_CA_FILE )
• AZURE_KUBERNETES_SNI_NAME - TLS Server Name Indication (optional)

The credential validates the configuration at construction time and throws InvalidOperationException if the configuration is invalid or incomplete.

Migration from ManagedIdentityCredential

If you're currently using ManagedIdentityCredential for workload identity in AKS and need to use identity binding mode, migrate to WorkloadIdentityCredential:

// Before (no identity binding support):
// var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// After (with identity binding support):
var credential = new WorkloadIdentityCredential(new WorkloadIdentityCredentialOptions
{
    IsAzureProxyEnabled = true
});

Sovereign cloud configuration

By default, credentials authenticate to the Microsoft Entra endpoint for the Azure Public Cloud. To access resources in other clouds, such as Azure US Government or a private cloud, use one of the following solutions:

1. Configure credentials with the AuthorityHost property. For example:

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        AuthorityHost = AzureAuthorityHosts.AzureGovernment
    });

AzureAuthorityHosts defines authorities for well-known clouds.

2. Set the AZURE_AUTHORITY_HOST environment variable to the appropriate authority host URL. For example, https://login.microsoftonline.us/. Note that this setting affects all credentials in the environment. Use the previous solution to set the authority host on a specific credential.

Not all credentials require this configuration. Credentials that authenticate through a developer tool, such as AzureCliCredential, use that tool's configuration.

Credential classes

Credential chains

Authenticate Azure-hosted apps

Authenticate service principals

Authenticate users

Authenticate via development tools