Azure.Identity 1.12.0

Azure Identity .NET 客户端库

Azure Identity 库为 Azure SDK 提供了 Microsoft Entra ID (之前称为 Azure Active Directory) 认证令牌支持。它提供了一组 TokenCredential 实现，可用来构建支持 Microsoft Entra 认证令牌的 Azure SDK 客户端。

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

入门

安装包

使用 NuGet 安装 .NET Azure Identity 客户端库

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 命令。对于在具有默认网络浏览器的系统上运行的用户，Azure CLI 将打开浏览器以进行用户认证。

对于没有默认网络浏览器的系统，az login 命令将使用设备代码验证流程。用户也可以通过指定 --use-device-code 参数强制 Azure CLI 使用设备代码流程而不是打开浏览器。

通过 Azure Developer CLI 认证

在 IDE 外编码的开发者也可以使用 Azure Developer CLI 进行认证。使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的应用程序可以通过在本地运行时使用此账户进行认证。

要使用 Azure Developer CLI 认证，用户可以运行命令 azd auth login。对于在具有默认网络浏览器的系统上运行的用户，Azure Developer CLI 将打开浏览器以进行用户认证。

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

通过 Azure PowerShell 认证

在 IDE 外编码的开发者也可以使用 Azure PowerShell 进行认证。使用 DefaultAzureCredential 或 AzurePowerShellCredential 的应用程序可以通过在本地运行时使用此账户进行认证。

要使用 Azure PowerShell 进行身份验证，用户可以运行命令 Connect-AzAccount。对于运行默认网络浏览器且 Azure PowerShell 版本为 5.0.0 或更高版本的系统，它会启动浏览器来验证用户。

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

关键概念

凭据

凭据是一个类，其中包含或可以获取服务客户端用于验证请求所需的数据。Azure SDK 中的所有服务客户端在其构造时都会接受凭据。服务客户端使用这些凭据来验证对服务的请求。

Azure Identity 库专注于使用 Microsoft Entra ID 的 OAuth 身份验证，并提供了一系列凭证类，以获取 Microsoft Entra 令牌来验证服务请求。该库中所有凭证类都是 Azure.Core 中的 TokenCredential 抽象类的实现，可以用于构造具有验证功能的服务客户端。

参阅 凭证类 以获取所有可用的凭证类型的完整列表。

DefaultAzureCredential

DefaultAzureCredential 适用于大多数应用最终要在 Azure 上运行的场景。这是因为 DefaultAzureCredential 结合了部署时常用以进行身份验证的凭据和开发环境中用identity authenticate的凭据。

注意：DefaultAzureCredential 旨在通过处理具有合理默认行为的常见场景来简化 SDK 的入门。希望有更多控制或其场景不符合默认设置的 developer 应使用其他凭证类型。

DefaultAzureCredential 将按以下顺序尝试通过以下机制进行身份验证，一旦成功则停止

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

续订策略

从版本1.10.1开始，DefaultAzureCredential将尝试使用所有开发者凭据进行身份验证，直到成功为止，而不管之前开发者凭据遇到任何错误。例如，一个开发者凭据可能尝试获取令牌并失败，所以DefaultAzureCredential将继续到下一个凭据。已部署的服务凭据如果在尝试获取令牌时没有收到任何令牌，将通过抛出异常来停止该流。在版本1.10.1之前，如果token检索失败，开发者凭据也会类似地停止身份验证流程。

此行为允许尝试机器上所有的开发者凭据，同时具有可预测的已部署行为。

示例

使用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将回退到通过系统默认浏览器与开发者进行交互式身份验证。然后该示例通过启用交互式身份验证使用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客户端库进行身份验证。它还演示了您可以通过客户端ID或资源ID指定用户分配的托管标识。

客户端ID

要使用客户端ID，采用以下方法之一

1. 设置DefaultAzureCredentialOptions.ManagedIdentityClientId属性。例如

// When deployed to an Azure host, DefaultAzureCredential 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);

1. 设置环境变量AZURE_CLIENT_ID。

资源ID

要使用资源ID，设置DefaultAzureCredentialOptions.ManagedIdentityResourceId属性。资源ID采用以下形式：/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}。由于资源ID可以由惯例生成，因此当你在环境中有许多用户分配的托管标识时，它可能更方便。例如

string userAssignedResourceId = "<your managed identity resource ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityResourceId = new ResourceIdentifier(userAssignedResourceId)
    });

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

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

托管身份支持

通过 DefaultAzureCredential 或直接使用 ManagedIdentityCredential，以下 Azure 服务支持 托管身份身份验证

• Azure App Service 和 Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure 虚拟机
• Azure 虚拟机扩展集

截至版本 1.8.0，ManagedIdentityCredential 支持 令牌缓存。

示例

以下示例演示了使用 ManagedIdentityCredential 验证 Azure.Security.KeyVault.Secrets 客户端库中的 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 托管应用程序

验证服务主体

验证用户

通过开发工具进行验证

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

环境变量

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

具有密钥的服务主体

具有证书的服务主体

用户名和密码

托管标识身份（DefaultAzureCredential）

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

持续访问评估

从版本 1.10.0 开始，按请求 basis 可以访问由 Continuous Access Evaluation (CAE) 保护的资源。可以通过通过构造函数设置 TokenRequestContext 的 IsCaeEnabled 属性来启用此行为。CAE 不支持开发者和托管标识凭证。

令牌缓存

令牌缓存 是 Azure Identity 库提供的一项功能。该功能允许应用

• 在内存中（默认）或磁盘上（opt-in）缓存令牌。
• 提高弹性和性能。
• 减少放置在 Microsoft Entra ID 以获取访问令牌的请求数量。

Azure Identity 库提供内存和持久磁盘缓存。有关详细信息，请参阅令牌缓存文档。

代理身份验证

身份代理是一个在用户机器上运行的应用程序，用于管理连接账户的身份验证握手和令牌维护。目前仅支持Windows网络账户管理器（WAM）。要启用支持，请使用Azure.Identity.Broker包。有关使用WAM进行身份验证的详细信息，请参阅代理包文档。

故障排除

请查阅故障排除指南以了解如何诊断各种失败场景的详细信息。

错误处理

认证过程中出现的错误可以在任何调用服务的服务客户端方法的上下文中引发。这是因为首次从凭据请求令牌是在第一次调用服务时，后续的调用可能需要刷新令牌。为了区分这些失败与客户端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。要仅记录用于尝试认证和授权的账户的详细信息，将IsAccountIdentifierLoggingEnabled设置为true。

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

线程安全

我们保证所有凭据实例方法都是线程安全的，并且互不干扰（《线程安全指南》）（线程安全指南））。这确保了重新使用凭据实例的建议总是安全的，即使在跨线程的情况下也是如此。

附加概念

客户端选项 | 访问响应 | 诊断 | 模拟 | 客户端寿命

下一步操作

支持与Azure Identity进行认证的客户端库

列出的许多客户端库在此处支持使用TokenCredential和Azure身份库进行认证。您还可以在那里找到学习更多关于它们的使用方法的信息，包括额外的文档和示例。

已知问题

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

有关 Azure.Identity 库的开放问题请见此处。

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权，并且实际上确实对我们的贡献享有使用权。有关详细信息，请访问https://cla.microsoft.com。

在提交拉取请求时，CLA-bot将自动确定您是否需要提供CLA，并以适当的方式装饰PR（例如，标签，注释）。只需遵循机器人提供的说明。您只需在所有使用我们的CLA的仓库中进行一次操作。

本项目已采用Microsoft开源准则。有关更多信息，请参阅准则FAQ或通过[email protected]联系以提出任何额外的问题或评论。