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

适用于 JavaScript 的 Azure 标识客户端库 - 版本 4.4.1

Azure 标识库通过一组方便的 TokenCredential 实现提供 Microsoft Entra ID（以前为 Azure Active Directory） 令牌身份验证。

有关各种凭据的示例，请参阅 Azure 标识示例页。

关键链接：

• 源代码
• 包 （npm）
• API 参考文档
• Microsoft Entra ID 文档
• 示例

开始

当前支持的环境

• LTS 版本的 Node.js
  • 注意： 如果应用程序在 Node.js v8 或更低版本上运行，并且无法将 Node.js 版本升级到最新的稳定版本，则将 @azure/identity 依赖项固定到版本 1.1.0。
• Safari、Chrome、Edge 和 Firefox 的最新版本。
  • 注意：在此库中导出的不同凭据中，InteractiveBrowserCredential 是浏览器中唯一受支持的凭据。

有关详细信息，请参阅我们的 支持策略。

安装包

使用 npm安装 Azure 标识：

npm install --save @azure/identity

先决条件

• Azure 订阅。
• 可选：Azure CLI 和/或 Azure PowerShell 也可用于在开发环境中进行身份验证和管理帐户角色。

何时使用 @azure/identity

@azure/identity 公开的凭据类侧重于提供在本地、开发环境和生产环境中对 Azure SDK 客户端进行身份验证的最直接方法。 我们旨在简单合理地支持身份验证协议，以涵盖 Azure 上可能的大部分身份验证方案。 我们正在积极扩展，以涵盖更多方案。 有关提供的凭据的完整列表，请参阅 凭据类 部分。

Node.js支持 @azure/identity 提供的所有凭据类型。 对于浏览器，InteractiveBrowserCredential 是用于基本身份验证方案的凭据类型。

@azure/identity 提供的大多数凭据类型都使用适用于 JavaScript 的 Microsoft 身份验证库（MSAL.js）。 具体而言，我们使用 v2 MSAL.js 库，这些库将 OAuth 2.0 授权代码流与 PKCE 配合使用，并且 符合 OpenID 的。 虽然 @azure/identity 侧重于简单性，MSAL.js 库（如 @azure/msal-common、@azure/msal-node和 @azure/msal-browser）旨在为 Azure 支持的身份验证协议提供可靠的支持。

何时使用其他内容

@azure/identity 凭据类型是 @azure/core-auth's TokenCredential 类的实现。 原则上，任何具有满足 getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>getToken 方法的对象都将作为 TokenCredential工作。 这意味着开发人员可以编写自己的凭据类型以支持 @azure/identity未涵盖的身份验证案例。 若要了解详细信息，请参阅 自定义凭据。

尽管我们的凭据类型支持许多高级案例，但开发人员可能需要完全控制身份验证协议。 对于该用例，我们建议直接使用适用于 JavaScript 的 Microsoft 身份验证库（MSAL.js）。 可以通过以下链接阅读详细信息：

• 我们在 Azure 标识示例 页上描绘了 @azure/identity 的一些高级用例。
  • 在那里，我们专门有一个 高级示例 部分。
  • 我们还提供了一个部分，演示如何 直接MSAL 进行身份验证。

对于浏览器中的高级身份验证工作流，我们提供了一个部分，其中展示了如何使用 @azure/msal-browser 库直接对 Azure SDK 客户端进行身份验证。

在开发环境中对客户端进行身份验证

虽然我们建议在 Azure 托管应用程序中使用托管标识，但开发人员通常使用自己的帐户在本地调试和执行代码时对 Azure 服务的调用进行身份验证。 有几个开发人员工具可用于在开发环境中执行此身份验证。

通过 Azure 开发人员 CLI 进行身份验证

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

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

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

通过 Azure CLI 进行身份验证

使用 AzureCliCredential的应用程序（无论是直接还是通过 DefaultAzureCredential）可以在本地运行时使用 Azure CLI 帐户对应用程序中的调用进行身份验证。

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

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

通过 Azure PowerShell 进行身份验证

使用 AzurePowerShellCredential的应用程序（无论是直接还是通过 DefaultAzureCredential）可以使用连接到 Azure PowerShell 的帐户在本地运行时对应用程序中的调用进行身份验证。

若要使用 Azure PowerShell 进行身份验证， 用户可以运行 Connect-AzAccount cmdlet。 默认情况下，与 Azure CLI 一样，Connect-AzAccount 将启动默认 Web 浏览器以对用户帐户进行身份验证。

如果会话中不支持交互式身份验证，则 -UseDeviceAuthentication 参数将强制 cmdlet 改用设备代码身份验证流，类似于 Azure CLI 凭据中的相应选项。

通过 Visual Studio Code 进行身份验证

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

若要在 Visual Studio Code 中进行身份验证，请确保已安装 Azure 帐户扩展。 安装后，打开 命令面板 并运行 Azure：登录 命令。

此外，请使用 @azure/identity-vscode 插件包。 此包提供 VisualStudioCodeCredential 的依赖项并启用它。 请参阅 插件。

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

在浏览器中对客户端进行身份验证

为了在 Web 浏览器中对 Azure SDK 客户端进行身份验证，我们提供了 InteractiveBrowserCredential，这些客户端可以设置为使用重定向或弹出窗口来完成身份验证流。 必须先在 Azure 门户中为 Web 应用程序创建 Azure 应用注册 。

关键概念

如果这是你第一次使用 @azure/identity 或 Microsoft Entra ID，请先阅读 将 @azure/identity 与 Microsoft Entra ID 一起使用。 本文档更深入地了解平台以及如何正确配置 Azure 帐户。

凭据

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

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

请参阅 凭据类。

DefaultAzureCredential

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

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

如果从 Node.js使用，DefaultAzureCredential 将尝试通过以下机制进行身份验证，以便：

1. 环境 - DefaultAzureCredential 将读取通过 环境变量指定的帐户信息 并使用它进行身份验证。
2. 工作负荷标识 - 如果应用程序部署到启用了托管标识的 Azure Kubernetes 服务，DefaultAzureCredential 将对其进行身份验证。
3. 托管标识 - 如果应用程序部署到启用了托管标识的 Azure 主机，DefaultAzureCredential 将使用该帐户进行身份验证。
4. Azure CLI - 如果开发人员已通过 Azure CLI az login 命令对帐户进行身份验证，DefaultAzureCredential 将使用该帐户进行身份验证。
5. Azure PowerShell - 如果开发人员使用 Azure PowerShell 模块 Connect-AzAccount 命令进行身份验证，DefaultAzureCredential 将使用该帐户进行身份验证。
6. Azure 开发人员 CLI - 如果开发人员已通过 Azure 开发人员 CLI azd auth login 命令对帐户进行身份验证，DefaultAzureCredential 将使用该帐户进行身份验证。

延续策略

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

这样，就可以在计算机上尝试所有开发人员凭据，同时具有可预测的部署行为。

有关 VisualStudioCodeCredential 的说明

由于 已知问题，VisualStudioCodeCredential 已从 DefaultAzureCredential 令牌链中删除。 在将来的版本中解决此问题时，将还原此更改。

插件

Azure Identity for JavaScript 提供了一个插件 API，使我们能够通过单独的 插件包提供某些功能。 @azure/identity 包导出可用于启用插件的顶级函数（useIdentityPlugin）。 我们提供了两个插件包：

• @azure/identity-broker，它通过本机代理（例如 Web 帐户管理器）提供中转身份验证支持。
• @azure/identity-cache-persistence，它使用操作系统提供的本机安全存储系统在 Node.js 中提供持久性令牌缓存。 此插件允许缓存 access_token 值跨会话保留，这意味着只要缓存令牌可用，就不需要重复交互式登录流。

例子

可以在 Azure 标识示例页中找到使用各种凭据的更多示例

使用 DefaultAzureCredential 进行身份验证

此示例演示如何使用 DefaultAzureCredential对 @azure/keyvault-keys 客户端库中的 KeyClient 进行身份验证。

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

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

相对常见的方案涉及对 Azure 资源使用用户分配的托管标识进行身份验证。 浏览有关使用 DefaultAzureCredential 对用户分配的托管标识进行身份验证的 示例，了解如何使用环境变量或在代码中配置这一任务。

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

虽然 DefaultAzureCredential 通常是开始为 Azure 开发应用程序的最快捷方法，但更高级的用户可能需要自定义身份验证时考虑的凭据。 ChainedTokenCredential 使用户能够合并多个凭据实例来定义自定义凭据链。 此示例演示如何创建一个 ChainedTokenCredential，该 ChainedTokenCredential 将尝试使用两个不同配置的 ClientSecretCredential实例进行身份验证，然后对 @azure/keyvault-keys中的 KeyClient 进行身份验证：

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

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

托管标识支持

托管标识身份验证 通过以下 Azure 服务直接通过 DefaultAzureCredential 或 ManagedIdentityCredential 凭据类提供支持：

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

有关如何使用托管标识进行身份验证的示例，请参阅 示例。

云配置

凭据默认为 Azure 公有云的 Microsoft Entra 终结点进行身份验证。 若要访问其他云（例如 Azure 政府版或私有云）中的资源，请使用构造函数中的 authorityHost 参数配置凭据。 AzureAuthorityHosts 接口定义已知云的颁发机构。 对于美国政府云，可以这样实例化凭据：

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

并非所有凭据都需要此配置。 通过开发工具（如 AzureCliCredential）进行身份验证的凭据使用该工具的配置。 同样，VisualStudioCodeCredential 接受 authorityHost 参数，但默认为与 Visual Studio Code Azure：云 设置匹配的 authorityHost。

凭据类

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

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

对服务主体进行身份验证

凭据	用法	例	参考
AzurePipelinesCredential	支持 Azure Pipelines 上的 Microsoft Entra 工作负荷 ID。	示例
ClientAssertionCredential	使用签名的客户端断言对服务主体进行身份验证。	示例	服务主体身份验证
ClientCertificateCredential	使用证书对服务主体进行身份验证。	示例	服务主体身份验证
ClientSecretCredential	使用机密对服务主体进行身份验证。	示例	服务主体身份验证

对用户进行身份验证

凭据	用法	例	参考
AuthorizationCodeCredential	使用以前获取的授权代码对用户进行身份验证。	示例	OAuth2 身份验证代码
DeviceCodeCredential	以交互方式在具有有限 UI 的设备上对用户进行身份验证。	示例	设备代码身份验证
InteractiveBrowserCredential	使用默认系统浏览器以交互方式对用户进行身份验证。 在此处阅读有关这种情况如何发生的详细信息 。	示例	OAuth2 身份验证代码
OnBehalfOfCredential	通过请求链传播委托的用户标识和权限		代理身份验证
UsernamePasswordCredential	使用用户名和密码对用户进行身份验证。	示例	用户名 + 密码身份验证

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

凭据	用法	例	参考
AzureCliCredential	使用 Azure CLI 在开发环境中进行身份验证。	示例	Azure CLI 身份验证
AzureDeveloperCliCredential	在开发环境中使用 Azure 开发人员 CLI 中已启用的用户或服务主体进行身份验证。		Azure 开发人员 CLI 参考
AzurePowerShellCredential	使用 Azure PowerShell 在开发环境中进行身份验证。	示例	Azure PowerShell 身份验证
VisualStudioCodeCredential	当用户登录到 Visual Studio Code Azure 帐户扩展时进行身份验证。		VS Code Azure 帐户扩展

环境变量

可以使用环境变量配置 DefaultAzureCredential 和 EnvironmentCredential。 每种类型的身份验证都需要特定变量的值。

具有机密的服务主体

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

具有证书的服务主体

变量名称	价值
AZURE_CLIENT_ID	Microsoft Entra 应用程序的 ID
AZURE_TENANT_ID	应用程序的Microsoft Entra 租户的 ID
AZURE_CLIENT_CERTIFICATE_PATH	PEM 编码的证书文件的路径，包括私钥
AZURE_CLIENT_CERTIFICATE_PASSWORD	证书文件的密码（如果有）

用户名和密码

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

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

持续访问评估

从版本 3.3.0 开始，可以按请求访问受 持续访问评估（CAE）保护的资源。 可以使用 GetTokenOptions.enableCae(boolean) API启用此功能。 开发人员凭据不支持 CAE。

令牌缓存

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

• 在内存（默认值）和磁盘上缓存令牌（选择加入）。
• 提高复原能力和性能。
• 减少向 Microsoft Entra ID 发出的获取访问令牌的请求数。

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

中转身份验证

身份验证代理是在用户计算机上运行并管理已连接帐户的身份验证握手和令牌维护的应用程序。 目前，仅支持 Windows Web 帐户管理器（WAM）。 若要启用支持，请使用 @azure/identity-broker 包。 有关使用 WAM 进行身份验证的详细信息，请参阅 中转站插件文档。

故障 排除

有关故障排除的帮助，请参阅 故障排除指南。

后续步骤

阅读文档

可以在我们的 文档网站找到此库的 API 文档。

客户端库支持

Azure SDK 上列出的客户端和管理库 支持Microsoft Entra 身份验证接受来自此库的凭据。 在文档（从发布页面链接）中了解有关使用这些库的详细信息。

已知问题

Azure AD B2C 支持

此库不支持 Azure AD B2C 服务。

有关其他打开的问题，请参阅库 GitHub 存储库。

提供反馈

如果遇到 bug 或有建议，提出问题。

贡献

若要参与此库，请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。