AgentSkillsCN

azure-identity-dotnet

Azure Identity SDK for .NET。这是一款用于 Azure SDK 客户端的认证库,依托 Microsoft Entra ID 实现身份验证。适用于 DefaultAzureCredential、托管身份、服务主体以及开发者凭据的管理。触发词:“Azure Identity”、“DefaultAzureCredential”、“ManagedIdentityCredential”、“ClientSecretCredential”、“authentication .NET”、“Azure auth”、“credential chain”。

SKILL.md
--- frontmatter
name: azure-identity-dotnet
description: |
  Azure Identity SDK for .NET. Authentication library for Azure SDK clients using Microsoft Entra ID. Use for DefaultAzureCredential, managed identity, service principals, and developer credentials. Triggers: "Azure Identity", "DefaultAzureCredential", "ManagedIdentityCredential", "ClientSecretCredential", "authentication .NET", "Azure auth", "credential chain".
package: Azure.Identity

Azure.Identity (.NET)

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

Installation

bash
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

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

Service Principal with Certificate

bash
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

bash
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:

OrderCredentialEnabled by Default
1EnvironmentCredentialYes
2WorkloadIdentityCredentialYes
3ManagedIdentityCredentialYes
4VisualStudioCredentialYes
5VisualStudioCodeCredentialYes
6AzureCliCredentialYes
7AzurePowerShellCredentialYes
8AzureDeveloperCliCredentialYes
9InteractiveBrowserCredentialNo

Basic Usage

csharp
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

csharp
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

csharp
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)

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

csharp
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

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

ChainedTokenCredential (Custom Chain)

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

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

Developer Credentials

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

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

Sovereign Clouds

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

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

Credential Types Reference

CategoryCredentialPurpose
ChainsDefaultAzureCredentialPreconfigured chain for dev-to-prod
ChainedTokenCredentialCustom credential chain
Azure-HostedManagedIdentityCredentialAzure managed identity
WorkloadIdentityCredentialKubernetes workload identity
EnvironmentCredentialEnvironment variables
Service PrincipalClientSecretCredentialClient ID + secret
ClientCertificateCredentialClient ID + certificate
ClientAssertionCredentialSigned client assertion
UserInteractiveBrowserCredentialBrowser-based auth
DeviceCodeCredentialDevice code flow
OnBehalfOfCredentialDelegated identity
DeveloperAzureCliCredentialAzure CLI
AzurePowerShellCredentialAzure PowerShell
AzureDeveloperCliCredentialAzure Developer CLI
VisualStudioCredentialVisual Studio

Best Practices

1. Use Deterministic Credentials in Production

csharp
// Development
var devCredential = new DefaultAzureCredential();

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

2. Reuse Credential Instances

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

csharp
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

csharp
using Azure.Core.Diagnostics;

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

Error Handling

csharp
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

ExceptionDescription
AuthenticationFailedExceptionBase exception for authentication errors
CredentialUnavailableExceptionCredential cannot authenticate in current environment
AuthenticationRequiredExceptionInteractive 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

SDKPurposeInstall
Azure.IdentityAuthentication (this SDK)dotnet add package Azure.Identity
Microsoft.Extensions.AzureDI integrationdotnet add package Microsoft.Extensions.Azure
Azure.Identity.BrokerBrokered auth (Windows)dotnet add package Azure.Identity.Broker

Reference Links