azure-identity-dotnet

Azure.Identity (.NET)

Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).

Installation

dotnet add package Azure.Identity

# For ASP.NET Core
dotnet add package Microsoft.Extensions.Azure

# For brokered authentication (Windows)
dotnet add package Azure.Identity.Broker

Current Versions: Stable v1.17.1, Preview v1.18.0-beta.2

Environment Variables

Service Principal with Secret

AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_SECRET=<client-secret-value>

Service Principal with Certificate

AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_CERTIFICATE_PATH=<path-to-pfx-or-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<certificate-password>  # Optional

Managed Identity

AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id>  # Only for user-assigned

DefaultAzureCredential

The recommended credential for most scenarios. Tries multiple authentication methods in order:

| Order | Credential | Enabled by Default |

|-------|------------|-------------------|

| 1 | EnvironmentCredential | Yes |

| 2 | WorkloadIdentityCredential | Yes |

| 3 | ManagedIdentityCredential | Yes |

| 4 | VisualStudioCredential | Yes |

| 5 | VisualStudioCodeCredential | Yes |

| 6 | AzureCliCredential | Yes |

| 7 | AzurePowerShellCredential | Yes |

| 8 | AzureDeveloperCliCredential | Yes |

| 9 | InteractiveBrowserCredential | No |

Basic Usage

using Azure.Identity;
using Azure.Storage.Blobs;

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

ASP.NET Core with Dependency Injection

using Azure.Identity;
using Microsoft.Extensions.Azure;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://myaccount.blob.core.windows.net"));
    clientBuilder.AddSecretClient(
        new Uri("https://myvault.vault.azure.net"));
    
    // Uses DefaultAzureCredential by default
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Customizing DefaultAzureCredential

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeManagedIdentityCredential = false,
        ExcludeVisualStudioCredential = false,
        ExcludeAzureCliCredential = false,
        ExcludeInteractiveBrowserCredential = false, // Enable interactive
        TenantId = "<tenant-id>",
        ManagedIdentityClientId = "<user-assigned-mi-client-id>"
    });

Credential Types

ManagedIdentityCredential (Production)

// System-assigned managed identity
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// User-assigned by client ID
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<client-id>"));

// User-assigned by resource ID
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedResourceId("<resource-id>"));

ClientSecretCredential

var credential = new ClientSecretCredential(
    tenantId: "<tenant-id>",
    clientId: "<client-id>",
    clientSecret: "<client-secret>");

var client = new SecretClient(
    new Uri("https://myvault.vault.azure.net"),
    credential);

ClientCertificateCredential

var certificate = X509CertificateLoader.LoadCertificateFromFile("MyCertificate.pfx");
var credential = new ClientCertificateCredential(
    tenantId: "<tenant-id>",
    clientId: "<client-id>",
    certificate);

ChainedTokenCredential (Custom Chain)

var credential = new ChainedTokenCredential(
    new ManagedIdentityCredential(),
    new AzureCliCredential());

var client = new SecretClient(
    new Uri("https://myvault.vault.azure.net"),
    credential);

Developer Credentials

// Azure CLI
var credential = new AzureCliCredential();

// Azure PowerShell
var credential = new AzurePowerShellCredential();

// Azure Developer CLI (azd)
var credential = new AzureDeveloperCliCredential();

// Visual Studio
var credential = new VisualStudioCredential();

// Interactive Browser
var credential = new InteractiveBrowserCredential();

Environment-Based Configuration

// Production vs Development
TokenCredential credential = builder.Environment.IsProduction()
    ? new ManagedIdentityCredential("<client-id>")
    : new DefaultAzureCredential();

Sovereign Clouds

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

// Available authority hosts:
// AzureAuthorityHosts.AzurePublicCloud (default)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina
// AzureAuthorityHosts.AzureGermany

Credential Types Reference

| Category | Credential | Purpose |

|----------|------------|---------|

| Chains | DefaultAzureCredential | Preconfigured chain for dev-to-prod |

| | ChainedTokenCredential | Custom credential chain |

| Azure-Hosted | ManagedIdentityCredential | Azure managed identity |

| | WorkloadIdentityCredential | Kubernetes workload identity |

| | EnvironmentCredential | Environment variables |

| Service Principal | ClientSecretCredential | Client ID + secret |

| | ClientCertificateCredential | Client ID + certificate |

| | ClientAssertionCredential | Signed client assertion |

| User | InteractiveBrowserCredential | Browser-based auth |

| | DeviceCodeCredential | Device code flow |

| | OnBehalfOfCredential | Delegated identity |

| Developer | AzureCliCredential | Azure CLI |

| | AzurePowerShellCredential | Azure PowerShell |

| | AzureDeveloperCliCredential | Azure Developer CLI |

| | VisualStudioCredential | Visual Studio |

Best Practices

1. Use Deterministic Credentials in Production

// Development
var devCredential = new DefaultAzureCredential();

// Production - use specific credential
var prodCredential = new ManagedIdentityCredential("<client-id>");

2. Reuse Credential Instances

// Good: Single credential instance shared across clients
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);

3. Configure Retry Policies

var options = new ManagedIdentityCredentialOptions(
    ManagedIdentityId.FromUserAssignedClientId(clientId))
{
    Retry =
    {
        MaxRetries = 3,
        Delay = TimeSpan.FromSeconds(0.5),
    }
};
var credential = new ManagedIdentityCredential(options);

4. Enable Logging for Debugging

using Azure.Core.Diagnostics;

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

Error Handling

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

var client = new SecretClient(
    new Uri("https://myvault.vault.azure.net"),
    new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed: {e.Message}");
}
catch (CredentialUnavailableException e)
{
    Console.WriteLine($"Credential Unavailable: {e.Message}");
}

Key Exceptions

| Exception | Description |

|-----------|-------------|

| AuthenticationFailedException | Base exception for authentication errors |

| CredentialUnavailableException | Credential cannot authenticate in current environment |

| AuthenticationRequiredException | Interactive authentication is required |

Managed Identity Support

Supported Azure services:

Thread Safety

All credential implementations are thread-safe. A single credential instance can be safely shared across multiple clients and threads.

Related SDKs

| SDK | Purpose | Install |

|-----|---------|---------|

| Azure.Identity | Authentication (this SDK) | dotnet add package Azure.Identity |

| Microsoft.Extensions.Azure | DI integration | dotnet add package Microsoft.Extensions.Azure |

| Azure.Identity.Broker | Brokered auth (Windows) | dotnet add package Azure.Identity.Broker |

Reference Links

| Resource | URL |

|----------|-----|

| NuGet Package | https://www.nuget.org/packages/Azure.Identity |

| API Reference | https://learn.microsoft.com/dotnet/api/azure.identity |

| Credential Chains | https://learn.microsoft.com/dotnet/azure/sdk/authentication/credential-chains |

| Best Practices | https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices |

| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity |