azure-identity-dotnet – DevOps & Infrastructure skill for AI agents

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

Version context: Examples reference the 1.17/1.18 generation; verify the installed package and target framework rather than treating these as current releases.

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

Credential chains and broker inclusion change with SDK version and optional packages. Check the effective identity/tenant and constrain production credentials explicitly; authentication alone grants no resource-operation authority. Keep tokens, certificate passwords and diagnostic output private. The certificate-loading example needs a runtime supporting X509CertificateLoader and a private-key-bearing PKCS#12 file. See [credential chains](https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication/credential-chains) and [PKCS#12 loading](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509certificateloader.loadpkcs12fromfile).

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.LoadPkcs12FromFile(
    "MyCertificate.pfx", Environment.GetEnvironmentVariable("CERTIFICATE_PASSWORD"));
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 K

… (full content is in the download package)