Azure Identity .NET

azure-identity-dotnet

分类通用

作者Agentic Awesome Skills 社区

许可MIT

评分4.70/5

使用5.1K

Azure.Identity (.NET)

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

安装

bash

dotnet add package Azure.Identity
适用于 ASP.NET Core
dotnet add package Microsoft.Extensions.Azure
适用于代理身份验证 (Windows)
dotnet add package Azure.Identity.Broker

当前版本：稳定版 v1.17.1，预览版 v1.18.0-beta.2

环境变量

使用密钥的服务主体

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_CERTIFICATE_PATH=<path-to-pfx-or-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<certificate-password>  # 可选

托管身份

bash

AZURE_CLIENT_ID=<user-assigned-managed-identity-client-id>  # 仅适用于用户分配的身份

DefaultAzureCredential

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

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

基础用法

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 依赖注入

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

自定义 DefaultAzureCredential

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

凭据类型

ManagedIdentityCredential (生产环境)

csharp

// 系统分配的托管身份
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);
// 通过客户端 ID 指定的用户分配身份
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
// 通过资源 ID 指定的用户分配身份
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUser

AssignedResourceId("<resource-id>"));

code

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

code

### ClientCertificateCredential

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

code

### ChainedTokenCredential (自定义链)

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

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

code

### 开发者凭据

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

code

## 基于环境的配置

csharp
// 生产环境 vs 开发环境
TokenCredential credential = builder.Environment.IsProduction()
? new ManagedIdentityCredential("<client-id>")
: new DefaultAzureCredential();

code

## 主权云 (Sovereign Clouds)

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

// 可用的权限主机：
// AzureAuthorityHosts.AzurePublicCloud (默认)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina
// AzureAuthorityHosts.AzureGermany

code

## 凭据类型参考
| 类别 | 凭据 | 用途 |
|----------|------------|---------|
| 链 (Chains) | 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. 在生产环境中使用确定性凭据

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

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

code

### 2. 复用凭据实例

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

code

### 3. 配置重试策略

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

code

### 4. 启用日志进行调试

csharp
using Azure.Core.Diagnostics;

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

code

## 错误处理

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


关键异常

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


托管身份支持
支持的 Azure 服务：
Azure App Service 和 Azure Functions

Azure Arc

Azure Cloud Shell

Azure Kubernetes Service (AKS)

Azure Service Fabric

Azure 虚拟机 (Virtual Machines)

Azure 虚拟机规模集 (Virtual Machine Scale Sets)

线程安全
所有凭据实现均是线程安全的。单个凭据实例可以在多个客户端和线程之间安全共享。
相关 SDK

| SDK | 用途 | 安装 | |-----|---------|---------| |Azure.Identity | 身份验证（本 SDK） | dotnet add package Azure.Identity| |Microsoft.Extensions.Azure | DI 依赖注入集成 | dotnet add package Microsoft.Extensions.Azure| |Azure.Identity.Broker | 代理身份验证 (Windows) | dotnet add package Azure.Identity.Broker` |

参考链接

| 资源 | URL |
|----------|-----|
| 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 .NET

Azure.Identity (.NET)

安装

适用于 ASP.NET Core

适用于代理身份验证 (Windows)

环境变量

使用密钥的服务主体

使用证书的服务主体

托管身份

DefaultAzureCredential

基础用法

ASP.NET Core 依赖注入

自定义 DefaultAzureCredential

凭据类型

ManagedIdentityCredential (生产环境)

最佳实践

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

关键异常

托管身份支持

线程安全

相关 SDK

参考链接

使用场景

局限性

扫码进交流群