适用于 JavaScript 的 Azure 标识客户端库中的凭据链

项目
01/10/2025

Azure 标识客户端库提供凭据，这些凭据是实现 Azure Core 库的 TokenCredential 接口的公共类。凭据表示从 Microsoft Entra ID 获取访问令牌的独特身份验证流。可以单独选择这些凭据或链接在一起，形成要尝试的有序身份验证机制序列。

个人凭据提供速度和确定性。如果身份验证失败，则表明凭据未通过身份验证。
链条提供备选方案。当凭据无法进行身份验证时，将尝试链中的下一个凭据。

设计身份验证流

使用 Azure SDK 客户端库时，第一步是向 Azure 进行身份验证。可通过多种选项进行身份验证来考虑，例如开发团队中使用的工具和 IDE、测试工作流和 CI/CD 等自动化工作流，以及托管平台（如 Azure 应用服务）。

从以下常见的认证流程中进行选择：

对开发人员使用各种 IDE 和 CLIs 向 Azure进行身份验证的团队使用DefaultAzureCredential。这允许最大的灵活性。这种灵活性是通过牺牲性能来实现的，用于验证链中的凭证，直到其中一个验证成功。
- 根据检测到的环境自动为你选择凭据之间的回退。
- 若要确认所选的凭据，请启用调试。
对团队使用ChainedTokenCredential，这些团队具有严格和范围的工具选择。例如，它们全部使用同一个 IDE 或 CLI 进行身份验证和操作。这样，团队可以选择确切的凭据及其顺序，这样的配置仍然提供灵活性，但性能成本有所降低。
- 无论凭据运行环境如何，都可以从凭据到凭据选择回退路径。
- 若要确认所选的凭据，请启用调试。
对于在所有环境中具有凭据确定性团队，可以使用控制流语句（例如 if/else）了解在每个环境中选择的凭据。
- 没有备用的其他凭据类型。
- 无需调试以确定选择了哪个凭据，因为它已指定。

链式凭证的工作原理

在运行时，凭据链尝试使用序列的第一个凭据进行身份验证。如果该凭据无法获取访问令牌，则会尝试序列中的下一个凭据，依此方式，直到成功获取访问令牌。以下序列图说明了此行为：

图示 Azure 标识凭据序列流

使用 DefaultAzureCredential 实现灵活性

DefaultAzureCredential 是一个固定的预配置凭据链。它旨在支持许多环境，以及最常见的身份验证流和开发人员工具。在图形形式中，基础链如下所示：

DefaultAzureCredential 尝试凭据的顺序如下。

下单(O)	凭据	描述
1	环境	读取环境变量的集合，以确定是否为应用配置了应用程序服务主体（应用程序用户）。如果是这样，`DefaultAzureCredential` 使用这些值向 Azure 对应用进行身份验证。此方法最常用于服务器环境，但也可以在本地开发时使用。
2	工作负载标识	如果应用部署到启用了工作负荷标识的 Azure 主机，请对该帐户进行身份验证。
3	托管的标识	如果应用部署到启用了托管标识的 Azure 主机，请使用该托管标识向 Azure 验证应用。
4	Azure 命令行界面 (CLI)	如果开发人员使用 Azure CLI 的 `az login` 命令向 Azure 进行身份验证，请使用同一帐户向 Azure 验证应用。
5	Azure PowerShell	如果开发人员使用 Azure PowerShell 的 `Connect-AzAccount` cmdlet 向 Azure 进行身份验证，请使用同一帐户向 Azure 验证应用。
6	Azure Developer CLI	如果开发人员使用 Azure 开发人员 CLI 的 `azd auth login` 命令向 Azure 进行身份验证，请使用该帐户进行身份验证。

最简单的形式是，可以使用无参数版本的 DefaultAzureCredential，如下所示：

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    "https://<my_account_name>.blob.core.windows.net",
    credential
);

凭据在环境中是全局性的

DefaultAzureCredential 检查是否存在某些环境变量。有人可以在主机上的系统级别添加或修改这些环境变量。这些更改在全局范围内适用，因此会在该计算机上运行的任何应用中改变 DefaultAzureCredential 在运行时的行为。

使用 ChainedTokenCredential 实现精细粒度

ChainedTokenCredential 是一个空链，可向其添加凭据以满足应用的需求。例如，以下示例添加一个 ManagedIdentityCredential 实例，然后添加一个 AzureCliCredential 实例。

import { 
    ChainedTokenCredential, 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new ManagedIdentityCredential({ clientId: "<YOUR_CLIENT_ID>" }),
    new AzureCliCredential()
);

前面的代码示例创建由两个凭据组成的定制凭据链。首先尝试 ManagedIdentityCredential 的用户分配的托管标识变体，然后在必要时尝试 AzureCliCredential。在图形形式中，链如下所示：

显示托管标识和 Azure CLI 的 Azure 标识凭据链的图表。

提示

为了提高性能，请优化 生产环境的凭据排序。应最后添加用于本地开发环境的凭据。

调试链接凭据

若要排查凭据链，请启用 Azure SDK 日志记录。

通过