athility/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:

• Azure App Service and Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service (AKS)
• Azure Service Fabric
• Azure Virtual Machines
• Azure Virtual Machine Scale Sets

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 |