你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 标识客户端库 - 版本 1.10.3

Azure 标识库跨 Azure SDK 提供Microsoft Entra ID (Azure Active Directory) 令牌身份验证支持。 它提供了一组TokenCredential实现，可用于构造支持Microsoft Entra令牌身份验证的 Azure SDK 客户端。

源代码 | 包 (NuGet) | API 参考文档 | Microsoft Entra ID 文档

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 标识客户端库：

dotnet add package Azure.Identity

先决条件

• 一个 Azure 订阅。
• Azure CLI 还可用于在开发环境中进行身份验证、创建帐户和管理帐户角色。

验证客户端

在本地调试和执行代码时，开发人员通常使用自己的帐户对 Azure 服务的调用进行身份验证。 有几种开发人员工具可用于在开发环境中执行此身份验证。

通过 Visual Studio 进行身份验证

使用 Visual Studio 2017 或更高版本的开发人员可以通过 IDE 对Microsoft Entra帐户进行身份验证。 然后，使用 DefaultAzureCredential 或 VisualStudioCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。

若要在 Visual Studio 中进行身份验证，请选择“ 工具>选项 ”菜单以启动“选项”对话框。 然后导航到Azure Service Authentication使用 Microsoft Entra 帐户登录的选项。

通过 Visual Studio Code 进行身份验证

使用 Visual Studio Code 的开发人员可以使用 Azure 帐户扩展通过编辑器进行身份验证。 然后，使用 DefaultAzureCredential 或 VisualStudioCodeCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。

这是一个已知问题，VisualStudioCodeCredential不适用于低于 0.9.11 的 Azure 帐户扩展版本。 正在对此问题进行长期修复。 同时，请考虑 通过 Azure CLI 进行身份验证。

通过 Azure CLI 进行身份验证

在 IDE 外部编码的开发人员也可以使用 Azure CLI 进行身份验证。 然后，使用 DefaultAzureCredential 或 AzureCliCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。

若要使用 Azure CLI 进行身份验证，用户可以运行命令 az login。 对于在具有默认 Web 浏览器的系统上运行的用户，Azure CLI 将启动浏览器来对用户进行身份验证。

对于没有默认 Web 浏览器的系统，az login 命令将使用设备代码身份验证流。 用户还可以通过指定 --use-device-code 参数来强制 Azure CLI 使用设备代码流，而不是启动浏览器。

通过Azure Developer CLI进行身份验证

在 IDE 外部编码的开发人员也可以使用Azure Developer CLI进行身份验证。 然后，使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。

若要使用 Azure Developer CLI进行身份验证，用户可以运行命令 azd auth login。 对于在具有默认 Web 浏览器的系统上运行的用户，Azure Developer CLI将启动浏览器来对用户进行身份验证。

对于没有默认 Web 浏览器的系统，azd auth login --use-device-code 命令将使用设备代码身份验证流。

通过 Azure PowerShell 进行身份验证

在 IDE 外部编码的开发人员也可以使用 Azure PowerShell 进行身份验证。 然后，使用 DefaultAzureCredential 或 AzurePowerShellCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。

若要使用 Azure PowerShell 进行身份验证，用户可以运行命令 Connect-AzAccount。 对于在具有默认 Web 浏览器和 Azure PowerShell 5.0.0 或更高版本的系统上运行的用户，它将启动浏览器对用户进行身份验证。

对于没有默认 Web 浏览器的系统，Connect-AzAccount 命令将使用设备代码身份验证流。 用户还可以强制Azure PowerShell使用设备代码流，而不是通过指定 UseDeviceAuthentication 参数启动浏览器。

关键概念

凭据

凭据是一种类，包含或可以获取服务客户端对请求进行身份验证所需的数据。 Azure SDK 中的服务客户端在构造时接受凭据。 服务客户端使用这些凭据对服务的请求进行身份验证。

Azure 标识库侧重于使用Microsoft Entra ID 进行 OAuth 身份验证，并提供各种凭据类，这些类能够获取Microsoft Entra令牌来对服务请求进行身份验证。 此库中的所有凭据类都是 Azure.Core 中抽象类的TokenCredential实现，其中任何一个TokenCredential都可用于构造能够使用 进行身份验证的服务客户端。

有关可用凭据类型的完整列表，请参阅凭据 类 。

DefaultAzureCredential

适用于 DefaultAzureCredential 应用程序最终在 Azure 中运行的大多数方案。 这是因为 DefaultAzureCredential 会将部署期间常用于进行身份验证的凭据与开发环境中用于进行身份验证的凭据组合在一起。

注意： DefaultAzureCredential 旨在通过处理具有合理默认行为的常见方案来简化 SDK 入门。 对于想要拥有更多控制或其方案缺少默认设置的开发人员，应使用其他凭据类型。

DefaultAzureCredential 尝试通过以下机制进行身份验证（按此顺序），成功时停止：

1. 环境 - DefaultAzureCredential 将读取通过 环境变量 指定的帐户信息，并使用它来进行身份验证。
2. 工作负载标识 - 如果将应用程序部署到启用了工作负载标识的 Azure 主机， DefaultAzureCredential 将使用该帐户进行身份验证。
3. 托管标识 - 如果应用程序部署到启用了托管标识的 Azure 主机， DefaultAzureCredential 将使用该帐户进行身份验证。
4. Visual Studio - 如果开发人员已通过 Visual Studio 进行身份验证， DefaultAzureCredential 将使用该帐户进行身份验证。
5. Visual Studio Code - 当前默认排除，因为由于问题 #27263，通过 Visual Studio Code 进行 SDK 身份验证已中断。 VisualStudioCodeCredential修复到位后，DefaultAzureCredential将在流中重新启用 。 问题 #30525 跟踪此问题。 同时，Visual Studio Code用户可以使用 Azure CLI 对其开发环境进行身份验证。
6. Azure CLI - 如果开发人员已通过 Azure CLI az login 命令对帐户进行身份验证， DefaultAzureCredential 则 将使用该帐户进行身份验证。
7. Azure PowerShell - 如果开发人员已通过 Azure PowerShell Connect-AzAccount 命令对帐户进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。
8. Azure Developer CLI - 如果开发人员已通过 Azure Developer CLI azd auth login 命令进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。
9. 交互式浏览器 - 如果已启用，DefaultAzureCredential 将通过当前系统的默认浏览器以交互方式对开发人员进行身份验证。 默认情况下，此凭据类型处于禁用状态。

延续策略

从版本 1.10.1 开始， DefaultAzureCredential 将尝试使用所有开发人员凭据进行身份验证，直到一个成功，而不管以前的开发人员凭据是否遇到任何错误。 例如，开发人员凭据可能会尝试获取令牌但失败，因此 DefaultAzureCredential 将继续访问流中的下一个凭据。 如果已部署的服务凭据能够尝试检索令牌，但未收到令牌检索，则会停止流并引发异常。 在版本 1.10.1 之前，如果令牌检索失败，开发人员凭据同样会停止身份验证流。

此行为允许尝试计算机上的所有开发人员凭据，同时具有可预测的部署行为。

示例

使用 DefaultAzureCredential 进行身份验证

该示例演示如何使用 DefaultAzureCredential 对来自 Azure.Security.KeyVault.Secrets 客户端库的 SecretClient 进行身份验证。

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

使用 启用交互式身份验证 DefaultAzureCredential

默认情况下，交互式身份验证在 中 DefaultAzureCredential 处于禁用状态。 此示例演示启用 的交互式身份验证部分的 DefaultAzureCredential两种方法。 启用后， DefaultAzureCredential 如果没有其他凭据可用，将回退到通过系统的默认浏览器以交互方式对开发人员进行身份验证。 然后EventHubProducerClient，此示例使用DefaultAzureCredential启用了交互式身份验证的 对 Azure.Messaging.EventHubs 客户端库中的 进行身份验证。

// the includeInteractiveCredentials constructor parameter can be used to enable interactive authentication
var credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

var eventHubClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

使用 DefaultAzureCredential 指定用户分配的托管标识

许多 Azure 主机允许分配用户分配的托管标识。 此示例演示如何配置 DefaultAzureCredential 以在部署到 Azure 主机时对用户分配的标识进行身份验证。 然后，它使用凭据对来自 Azure.Storage.Blobs 客户端库的 BlobClient 进行身份验证。

// When deployed to an azure host, the default azure credential will authenticate the specified user assigned managed identity.

string userAssignedClientId = "<your managed identity client Id>";
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

除了通过代码配置 ManagedIdentityClientId 之外，还可以使用 AZURE_CLIENT_ID 环境变量对其进行设置。 使用 时，这两种方法是等效的 DefaultAzureCredential。

使用 ChainedTokenCredential 定义自定义身份验证流

虽然 DefaultAzureCredential 通常是开始为 Azure 开发应用程序的最快方法，但更高级的用户可能希望自定义身份验证时考虑的凭据。 ChainedTokenCredential 使用户能够组合多个凭据实例来定义自定义的凭据链。 此示例演示如何创建一个 ChainedTokenCredential ，它将尝试使用托管标识进行身份验证，如果托管标识在当前环境中不可用，则回退到通过 Azure CLI 进行身份验证。 然后，该凭据用于对来自 Azure.Messaging.EventHubs 客户端库的 EventHubProducerClient 进行身份验证。

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

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

var eventHubProducerClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

托管标识支持

对于以下 Azure 服务，通过 或 ManagedIdentityCredential 直接支持DefaultAzureCredential托管标识身份验证：

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

示例

这些示例演示了使用 从 Azure.Security.KeyVault.Secrets 客户端库对 ManagedIdentityCredential进行身份验证SecretClient。

使用用户分配的托管标识进行身份验证

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

使用系统分配的托管标识进行身份验证

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

云配置

凭据默认为向 Azure 公有云的 Microsoft Entra 终结点进行身份验证。 若要访问其他云中的资源（例如Azure 政府或私有云），请使用 AuthorityHost 参数配置凭据。 AzureAuthorityHosts 定义已知云的权威：

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

并非所有凭据都需要此配置。 通过开发工具（如 ） AzureCliCredential进行身份验证的凭据使用该工具的配置。

凭据类

对 Azure 托管的应用程序进行身份验证

凭据	使用情况
DefaultAzureCredential	提供简化的身份验证体验，以快速开始开发在 Azure 中运行的应用程序。
ChainedTokenCredential	允许用户定义组成多个凭据的自定义身份验证流。
EnvironmentCredential	通过环境变量中指定的凭据信息对服务主体或用户进行身份验证。
ManagedIdentityCredential	对 Azure 资源的托管标识进行身份验证。
WorkloadIdentityCredential	支持在 Kubernetes 上Microsoft Entra Workload ID。

对服务主体进行身份验证

凭据	使用情况	参考
ClientAssertionCredential	使用签名客户端断言对服务主体进行身份验证。
ClientCertificateCredential	使用证书对服务主体进行身份验证。	服务主体身份验证
ClientSecretCredential	使用机密对服务主体进行身份验证。	服务主体身份验证

对用户进行身份验证

凭据	使用情况	参考
AuthorizationCodeCredential	使用以前获取的授权代码对用户进行身份验证。	OAuth2 验证码
DeviceCodeCredential	以交互方式在具有有限 UI 的设备上对用户进行身份验证。	设备代码身份验证
InteractiveBrowserCredential	使用默认系统浏览器以交互方式对用户进行身份验证。	OAuth2 验证码
OnBehalfOfCredential	通过请求链传播委托的用户标识和权限。	代理身份验证
UsernamePasswordCredential	使用用户名和密码对用户进行身份验证。	用户名 + 密码身份验证

通过开发工具进行身份验证

凭据	使用情况	参考
AzureCliCredential	使用 Azure CLI 在开发环境中进行身份验证。	Azure CLI 身份验证
AzureDeveloperCliCredential	使用 Azure Developer CLI在开发环境中进行身份验证。	Azure Developer CLI参考
AzurePowerShellCredential	使用 Azure PowerShell 在开发环境中进行身份验证。	Azure PowerShell身份验证
VisualStudioCredential	使用 Visual Studio 在开发环境中进行身份验证。	Visual Studio 配置
VisualStudioCodeCredential	当用户登录到 Visual Studio Code Azure 帐户扩展时进行身份验证。	VS Code Azure 帐户扩展

注意： Azure 标识库中的所有凭据实现都是线程安全的，单个凭据实例可供多个服务客户端使用。

环境变量

DefaultAzureCredential 和 EnvironmentCredential 可通过环境变量进行配置。 每种类型的身份验证都需要特定变量的值：

具有机密的服务主体

变量名称	值
AZURE_CLIENT_ID	Microsoft Entra应用程序的 ID
AZURE_TENANT_ID	应用程序的Microsoft Entra租户的 ID
AZURE_CLIENT_SECRET	应用程序的客户端机密之一

具有证书的服务主体

变量名称	Value
AZURE_CLIENT_ID	Microsoft Entra应用程序的 ID
AZURE_TENANT_ID	应用程序的Microsoft Entra租户的 ID
AZURE_CLIENT_CERTIFICATE_PATH	PFX 或 PEM 编码的证书文件（包括私钥）的路径
AZURE_CLIENT_CERTIFICATE_PASSWORD	(可选) 保护证书文件的密码 (目前仅 PFX (PKCS12 支持) 证书)
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN	(可选) 在 x5c 标头中发送证书链以支持基于使用者名称/颁发者的身份验证

用户名和密码

变量名称	值
AZURE_CLIENT_ID	Microsoft Entra应用程序的 ID
AZURE_TENANT_ID	应用程序的Microsoft Entra租户的 ID
AZURE_USERNAME	用户名（通常为电子邮件地址）
AZURE_PASSWORD	该用户的密码

按上述顺序尝试进行配置。 例如，如果客户端机密和证书的值都存在，则将使用客户端机密。

连续访问评估

从版本 1.10.0 开始，可以按请求访问 受持续访问评估 (CAE) 保护的资源。 可以通过构造函数设置 IsCaeEnabled 的 TokenRequestContext 属性来启用此行为。 开发人员和托管标识凭据不支持 CAE。

令牌缓存

令牌缓存是 Azure 标识库提供的一项功能，它允许应用：

• 将令牌缓存在内存中 (默认) 或磁盘上， (选择加入) 。
• 提高复原能力和性能。
• 减少对Microsoft Entra ID 获取访问令牌的请求数。

Azure 标识库提供内存中缓存和永久性磁盘缓存。 有关更多详细信息，请参阅 令牌缓存文档

疑难解答

有关如何诊断各种故障方案的详细信息，请参阅 故障排除指南 。

错误处理。

在向服务发出请求的任何服务客户端方法上，都可能会引发身份验证引起的错误。 这是因为首次从凭据请求令牌是在首次调用服务时，任何后续调用都可能需要刷新令牌。 为了将这些故障与服务客户端中的故障区分开来，Azure 标识类会向异常消息中的错误源以及错误消息中提供 AuthenticationFailedException 详细信息。 根据应用程序的不同，这些错误可能可恢复，也可能不可恢复。

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
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}");
}

有关处理Microsoft Entra ID 或托管标识终结点请求失败导致的错误的详细信息，请参阅有关授权错误代码的 Microsoft Entra ID 文档。

日志记录

Azure 标识库提供的 日志记录功能 与 Azure SDK 的其余部分相同。

查看日志以帮助调试身份验证问题的最简单方法是启用控制台日志记录。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

可以使用诊断选项配置所有凭据，其方式与 SDK 中的其他客户端相同。

谨慎： Azure 标识库中的请求和响应包含敏感信息。 自定义输出时，必须采取预防措施来保护日志，以避免损害帐户安全性。

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

排查身份验证问题时，可能还需要启用敏感信息日志记录。 若要启用这种类型的日志记录，请将 IsLoggingContentEnabled 属性设置为 true。 若要仅记录用于尝试身份验证和授权的帐户的详细信息，请将 设置为 IsAccountIdentifierLoggingEnabledtrue。

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsAccountIdentifierLoggingEnabled = true
    }
};

线程安全

我们保证所有凭据实例方法都是线程安全的，并且彼此独立， (准则) 。 这可确保重用凭据实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

客户端选项 | 访问响应 | 诊断 | 嘲笑 | 客户端生存期

后续步骤

支持使用 Azure 标识进行身份验证的客户端库

此处列出的许多客户端库都支持使用 TokenCredential 和 Azure 标识库进行身份验证。 在链接中，还可以找到有关其用法的详细信息的链接，包括其他文档和示例。

已知问题

此库目前不支持与 Azure AD B2C 服务相关的方案。

可在此处找到库的Azure.Identity未结问题。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。