Azure Identity 库 for .NET
使用 Microsoft Entra ID 对 Azure SDK 客户端进行身份验证的库。
安装
dotnet add package Azure.Identity
# 用于 ASP.NET Core 集成
dotnet add package Microsoft.Extensions.Azure
# 用于代理身份验证和 Visual Studio Code 凭据支持
dotnet add package Azure.Identity.Broker
环境变量
服务主体与机密
AZURE_CLIENT_ID=<application-client-id>
AZURE_TENANT_ID=<directory-tenant-id>
AZURE_CLIENT_SECRET=<client-secret-value>
服务主体与证书
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> # 可选
托管标识
AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id> # 仅用于用户分配
DefaultAzureCredential
大多数场景推荐的凭据。按顺序尝试多种身份验证方法。请参阅 DefaultAzureCredential 概述 了解当前凭据链顺序和默认值。
基本用法
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 与依赖注入
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());
});
自定义 DefaultAzureCredential
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>"
});
凭据类型
ManagedIdentityCredential（生产环境）
// 系统分配托管标识
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);
// 用户分配（通过客户端 ID）
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
// 用户分配（通过资源 ID）
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedResourceId("<resource-id>"));
// 用户分配（通过对象 ID）
var credential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedObjectId("<object-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（自定义链）
var credential = new ChainedTokenCredential(
new ManagedIdentityCredential(),
new AzureCliCredential());
var client = new SecretClient(
new Uri("https://myvault.vault.azure.net"),
credential);
开发人员凭据
// 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();
基于环境的配置
// 生产环境 vs 开发环境
TokenCredential credential = builder.Environment.IsProduction()
? new ManagedIdentityCredential("<client-id>")
: new DefaultAzureCredential();
主权云
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
AuthorityHost = AzureAuthorityHosts.AzureGovernment
});
// 可用的权威主机：
// AzureAuthorityHosts.AzurePublicCloud（默认）
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina
凭据类型参考
| 类别 | 凭据 | 用途 |
|---|---|---|
| 链式 | 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 |
最佳实践
1. 在生产环境中使用确定性凭据
// 开发环境
var devCredential = new DefaultAzureCredential();
// 生产环境 - 使用特定凭据
var prodCredential = new ManagedIdentityCredential(
ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
2. 复用凭据实例
// 良好实践：跨多个客户端共享单个凭据实例
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);
3. 配置重试策略
var options = new ManagedIdentityCredentialOptions(
ManagedIdentityId.FromUserAssignedClientId(clientId))
{
Retry =
{
MaxRetries = 3,
Delay = TimeSpan.FromSeconds(0.5),
}
};
var credential = new ManagedIdentityCredential(options);
4. 启用日志记录以进行调试
using Azure.Core.Diagnostics;
using AzureEventSourceListener listener = new((args, message) =>
{
if (args is { EventSource.Name: "Azure-Identity" })
{
Console.WriteLine(message);
}
}, EventLevel.LogAlways);
错误处理
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}");
}
关键异常
| 异常 | 描述 |
|---|---|
AuthenticationFailedException | 身份验证错误的基础异常 |
CredentialUnavailableException | 当前环境中凭据无法进行身份验证 |
AuthenticationRequiredException | 需要交互式身份验证 |
托管标识支持
支持的 Azure 服务：
- Azure App Service 和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service (AKS)
- Azure Service Fabric
- Azure 虚拟机
- Azure 虚拟机规模集
线程安全
所有凭据实现都是线程安全的。单个凭据实例可以安全地在多个客户端和线程之间共享。
相关包
| 包 | 用途 | 安装 |
|---|---|---|
Azure.Identity | 身份验证（此库） | dotnet add package Azure.Identity |
Microsoft.Extensions.Azure | DI 集成 | dotnet add package Microsoft.Extensions.Azure |
Azure.Identity.Broker | 代理身份验证 | dotnet add package Azure.Identity.Broker |