Regtransfers/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

@ When to Use This skill is applicable to execute the workflow or actions described in the overview.

@ Limitations

• Use this skill only when the task clearly matches the scope described above.
• never treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.