azure-identity-dotnet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure.Identity (.NET)

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

一款使用Microsoft Entra ID（原Azure AD）为Azure SDK客户端提供支持的身份验证库。

Installation

安装

bash

dotnet add package Azure.Identity

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

dotnet add package Azure.Identity.Broker


**当前版本**：稳定版v1.17.1，预览版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>

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

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

bash

AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id>  # 仅适用于用户分配的托管标识

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

这是大多数场景下推荐使用的凭据。它会按顺序尝试多种身份验证方法：

顺序	凭据	默认启用
1	EnvironmentCredential	是
2	WorkloadIdentityCredential	是
3	ManagedIdentityCredential	是
4	VisualStudioCredential	是
5	VisualStudioCodeCredential	是
6	AzureCliCredential	是
7	AzurePowerShellCredential	是
8	AzureDeveloperCliCredential	是
9	InteractiveBrowserCredential	否

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

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

结合依赖注入的ASP.NET Core使用

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());
});

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"));
    
    // 默认使用DefaultAzureCredential
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Customizing DefaultAzureCredential

自定义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>"
    });

csharp

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeManagedIdentityCredential = false,
        ExcludeVisualStudioCredential = false,
        ExcludeAzureCliCredential = false,
        ExcludeInteractiveBrowserCredential = false, // 启用交互式验证
        TenantId = "<tenant-id>",
        ManagedIdentityClientId = "<user-assigned-mi-client-id>"
    });

Credential Types

凭据类型

ManagedIdentityCredential (Production)

ManagedIdentityCredential（生产环境）

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>"));

csharp

// 系统分配的托管标识
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// 通过客户端ID指定用户分配的托管标识
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<client-id>"));

// 通过资源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);

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

csharp

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

ChainedTokenCredential (Custom Chain)

ChainedTokenCredential（自定义凭据链）

csharp

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

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

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();

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();

// 交互式浏览器
var credential = new InteractiveBrowserCredential();

Environment-Based Configuration

基于环境的配置

csharp

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

csharp

// 生产环境 vs 开发环境
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

csharp

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

// 可用的授权主机：
// AzureAuthorityHosts.AzurePublicCloud（默认）
// 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

类别	凭据	用途
凭据链	`DefaultAzureCredential`	预配置的从开发到生产的凭据链
	`ChainedTokenCredential`	自定义凭据链
Azure托管环境	`ManagedIdentityCredential`	Azure托管标识
	`WorkloadIdentityCredential`	Kubernetes工作负载标识
	`EnvironmentCredential`	环境变量配置
服务主体	`ClientSecretCredential`	客户端ID + 密钥
	`ClientCertificateCredential`	客户端ID + 证书
	`ClientAssertionCredential`	已签名的客户端断言
用户	`InteractiveBrowserCredential`	基于浏览器的身份验证
	`DeviceCodeCredential`	设备代码流
	`OnBehalfOfCredential`	委托标识
开发人员工具	`AzureCliCredential`	Azure CLI
	`AzurePowerShellCredential`	Azure PowerShell
	`AzureDeveloperCliCredential`	Azure Developer CLI
	`VisualStudioCredential`	Visual Studio

Best Practices

最佳实践

1. Use Deterministic Credentials in Production

1. 在生产环境中使用确定性凭据

csharp

// Development
var devCredential = new DefaultAzureCredential();

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

csharp

// 开发环境
var devCredential = new DefaultAzureCredential();

// 生产环境 - 使用特定凭据
var prodCredential = new ManagedIdentityCredential("<client-id>");

2. Reuse Credential Instances

2. 复用凭据实例

csharp

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

csharp

// 推荐：单个凭据实例在多个客户端之间共享
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);

3. Configure Retry Policies

3. 配置重试策略

csharp

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

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

4. 启用日志以进行调试

csharp

using Azure.Core.Diagnostics;

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

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}");
}

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($"身份验证失败：{e.Message}");
}
catch (CredentialUnavailableException e)
{
    Console.WriteLine($"凭据不可用：{e.Message}");
}

Key Exceptions

主要异常

Exception	Description
`AuthenticationFailedException`	Base exception for authentication errors
`CredentialUnavailableException`	Credential cannot authenticate in current environment
`AuthenticationRequiredException`	Interactive authentication is required

异常	描述
`AuthenticationFailedException`	身份验证错误的基础异常
`CredentialUnavailableException`	当前环境中凭据无法进行身份验证
`AuthenticationRequiredException`	需要交互式身份验证

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

支持的Azure服务：

Azure应用服务和Azure Functions
Azure Arc
Azure Cloud Shell
Azure Kubernetes Service (AKS)
Azure Service Fabric
Azure虚拟机
Azure虚拟机规模集

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`

SDK	用途	安装命令
`Azure.Identity`	身份验证（本SDK）	`dotnet add package Azure.Identity`
`Microsoft.Extensions.Azure`	依赖注入集成	`dotnet add package Microsoft.Extensions.Azure`
`Azure.Identity.Broker`	代理身份验证（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

资源	链接
NuGet包	https://www.nuget.org/packages/Azure.Identity
API参考	https://learn.microsoft.com/dotnet/api/azure.identity
凭据链	https://learn.microsoft.com/dotnet/azure/sdk/authentication/credential-chains
最佳实践	https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices
GitHub源码	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity
",

azure-identity-dotnet

Original

Translation

Azure.Identity (.NET)

Azure.Identity (.NET)

Installation

安装

For ASP.NET Core

For ASP.NET Core

For brokered authentication (Windows)

For brokered authentication (Windows)

Environment Variables

环境变量

Service Principal with Secret

使用密钥的服务主体

Service Principal with Certificate

使用证书的服务主体

Managed Identity

托管标识

DefaultAzureCredential

DefaultAzureCredential

Basic Usage

基本用法

ASP.NET Core with Dependency Injection

结合依赖注入的ASP.NET Core使用

Customizing DefaultAzureCredential

自定义DefaultAzureCredential

Credential Types

凭据类型

ManagedIdentityCredential (Production)

ManagedIdentityCredential（生产环境）

ClientSecretCredential

ClientSecretCredential

ClientCertificateCredential

ClientCertificateCredential

ChainedTokenCredential (Custom Chain)

ChainedTokenCredential（自定义凭据链）

Developer Credentials

开发人员凭据

Environment-Based Configuration

基于环境的配置

Sovereign Clouds

主权云

Credential Types Reference

凭据类型参考

Best Practices

最佳实践

1. Use Deterministic Credentials in Production

1. 在生产环境中使用确定性凭据

2. Reuse Credential Instances

2. 复用凭据实例

3. Configure Retry Policies

3. 配置重试策略

4. Enable Logging for Debugging

4. 启用日志以进行调试

Error Handling

错误处理

Key Exceptions

主要异常

Managed Identity Support

托管标识支持

Thread Safety

线程安全

Related SDKs

相关SDK

Reference Links

参考链接