你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 JavaScript 的 Azure 标识客户端库 - 版本 4.1.0
Azure 标识库通过一组便捷的TokenCredential 实现，Microsoft Entra ID (以前是 Azure Active Directory) 令牌身份验证。
有关各种凭据的示例，请参阅 Azure 标识示例页。
关键链接：
入门
从 v1 迁移到 v2 @azure/identity
如果使用的是 的 @azure/identityv1，请参阅 迁移指南 以更新到 v2。
目前支持的环境
- LTS 版本的 Node.js
- 注意： 如果应用程序在 Node.js v8 或更低版本上运行，并且无法将 Node.js 版本升级到最新的稳定版本，请将
@azure/identity依赖项固定到版本 1.1.0。
- 注意： 如果应用程序在 Node.js v8 或更低版本上运行，并且无法将 Node.js 版本升级到最新的稳定版本，请将
- 最新版本的 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 大多数凭据类型都使用 Microsoft Authentication Library for JavaScript (MSAL.js) 。 具体而言，我们使用 v2 MSAL.js 库，这些库使用 OAuth 2.0 授权代码流和 PKCE ，并且 符合 OpenID。 MSAL.js @azure/identity 库（如 @azure/msal-common、 @azure/msal-node 和 @azure/msal-browser）旨在为 Azure 支持的身份验证协议提供可靠的支持。
何时使用其他内容
@azure/identity凭据类型是 @azure/core-auth 类的TokenCredential实现。 原则上，任何具有 getToken 满足 getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> 方法的对象都将作为 TokenCredential工作。 这意味着开发人员可以编写自己的凭据类型，以支持 未涵盖的 @azure/identity身份验证案例。 若要了解详细信息，请参阅 自定义凭据。
尽管凭据类型支持许多高级情况，但开发人员可能需要完全控制身份验证协议。 对于该用例，建议直接使用 适用于 JavaScript 的 Microsoft 身份验证库 (MSAL.js) 。 可以通过以下链接阅读详细信息：
- 我们在 Azure 标识示例页上描述了 的
@azure/identity一些高级用例。- 我们专门有一个 “高级示例” 部分。
- 我们还有一个部分，介绍如何 直接使用 MSAL 进行身份验证。
对于浏览器中的高级身份验证工作流，我们提供了一个部分，其中展示了如何使用 @azure/msal-browser 库直接对 Azure SDK 客户端进行身份验证。
在开发环境中对客户端进行身份验证
虽然我们建议在生产应用程序中使用托管标识或服务主体身份验证，但开发人员在本地调试和执行代码时，通常使用自己的帐户对 Azure 服务的调用进行身份验证。 有几种开发人员工具可用于在开发环境中执行此身份验证。
通过Azure Developer CLI进行身份验证
在 IDE 外部编码的开发人员也可以使用 [Azure Developer CLI][azure_developer_cli] 进行身份验证。 然后，使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。
若要使用 [Azure Developer CLI][azure_developer_cli]进行身份验证，用户可以运行命令 azd auth login。 对于在具有默认 Web 浏览器的系统上运行的用户，Azure Developer CLI将启动浏览器对用户进行身份验证。
对于没有默认 Web 浏览器的系统，azd auth login --use-device-code 命令将使用设备代码身份验证流。
通过 Azure CLI 进行身份验证
在本地运行时，无论 AzureCliCredential直接还是通过 DefaultAzureCredential使用 的应用程序，都可以使用 Azure CLI 帐户对应用程序中的调用进行身份验证。
若要使用 Azure CLI 进行身份验证，用户可以运行 az login 命令。 对于在具有默认 Web 浏览器的系统上运行的用户，Azure CLI 将启动浏览器以对用户进行身份验证。
对于没有默认 Web 浏览器的系统，az login 命令将使用设备代码身份验证流。 用户还可以通过指定 --use-device-code 参数来强制 Azure CLI 使用设备代码流，而不是启动浏览器。
通过 Azure PowerShell 进行身份验证
使用 AzurePowerShellCredential的应用程序，无论是直接还是通过 DefaultAzureCredential，都可以使用连接到 Azure PowerShell 的帐户在本地运行时对应用程序中的调用进行身份验证。
若要使用Azure PowerShell用户可运行 cmdletConnect-AzAccount。 默认情况下，ike 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 并启用它。 请参阅 插件。
这是一个已知问题，VisualStudioCodeCredential不适用于低于 0.9.11 的 Azure 帐户扩展版本。 正在对此问题进行长期修复。 同时，请考虑 通过 Azure CLI 进行身份验证。
在浏览器中对客户端进行身份验证
为了在 Web 浏览器中对 Azure SDK 客户端进行身份验证，我们提供了 InteractiveBrowserCredential，可以将其设置为使用重定向或弹出窗口来完成身份验证流。 必须先在 Web 应用程序的Azure 门户中创建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 将按顺序尝试通过以下机制进行身份验证：
- 环境 -
DefaultAzureCredential将读取通过 环境变量 指定的帐户信息，并使用它进行身份验证。 - 工作负载标识 - 如果将应用程序部署到启用了托管标识的Azure Kubernetes 服务，
DefaultAzureCredential则会使用它进行身份验证。 - 托管标识 - 如果应用程序部署到启用了托管标识的 Azure 主机，
DefaultAzureCredential将使用该帐户进行身份验证。 - Azure CLI - 如果开发人员已通过 Azure CLI
az login命令对帐户进行身份验证，DefaultAzureCredential则会使用该帐户进行身份验证。 - Azure PowerShell - 如果开发人员已使用 Azure PowerShell 模块
Connect-AzAccount命令进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。 - Azure Developer CLI - 如果开发人员已通过 Azure Developer CLI
azd auth login命令对帐户进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。
延续策略
从版本 3.3.0 开始， DefaultAzureCredential 将尝试使用所有开发人员凭据进行身份验证，直到成功，而不考虑以前开发人员凭据遇到的任何错误。 例如，开发人员凭据可能会尝试获取令牌但失败，因此 DefaultAzureCredential 将继续访问流中的下一个凭据。 如果已部署的服务凭据能够尝试检索令牌，但未收到令牌检索，则会停止流并引发异常。
这样，就可以尝试计算机上的所有开发人员凭据，同时具有可预测的部署行为。
有关的说明 VisualStudioCodeCredential
由于 已知问题， VisualStudioCodeCredential 已从令牌链中删除 DefaultAzureCredential 。 在将来的版本中解决此问题时，将还原此更改。
插件
适用于 JavaScript 的 Azure 标识提供了一个插件 API，使我们能够通过单独的 插件包提供某些功能。 包 @azure/identity 导出可用于启用插件的顶级函数 (useIdentityPlugin) 。 我们提供两个插件包：
@azure/identity-broker，它通过本机代理（如 Web 帐户管理器）提供中转身份验证支持。@azure/identity-cache-persistence，它使用操作系统提供的本机安全存储系统在 Node.js 中提供永久性令牌缓存。 此插件允许缓存access_token值跨会话保留，这意味着只要缓存的令牌可用，就不需要重复交互式登录流。
示例
可以在 Azure 标识示例页中找到使用不同凭据的更多示例
使用 进行身份验证 DefaultAzureCredential
此示例演示如何使用 从 @azure/keyvault-keys 客户端库对 DefaultAzureCredential进行身份验证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不同配置的 实例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但默认为authorityHost匹配Visual Studio Code的 Azure： Cloud 设置。
凭据类
对 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身份验证 |
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) 保护的资源。 可以使用 API 启用此功能GetTokenOptions.enableCae(boolean)。 开发人员凭据不支持 CAE。
令牌缓存
令牌缓存是 Azure 标识库提供的一项功能，它允许应用：
- 内存中的令牌 (默认) ，磁盘上的缓存令牌 (选择加入) 。
- 提高复原能力和性能。
- 减少Microsoft Entra ID获取访问令牌的请求数。
Azure 标识库提供内存中缓存和永久性磁盘缓存。 有关详细信息，请参阅 令牌缓存文档。
中介身份验证
身份验证代理是在用户计算机上运行并管理已连接帐户的身份验证握手和令牌维护的应用程序。 目前，仅支持 Windows Web 帐户管理器 (WAM) 。 若要启用支持，请使用 @azure/identity-broker 包。 有关使用 WAM 进行身份验证的详细信息，请参阅 Broker 插件文档。
故障排除
有关故障排除的帮助，请参阅 故障排除指南。
后续步骤
阅读文档
可以在文档站点上找到此库的 API 文档。
客户端库支持
Azure SDK 版本页上列出的支持Microsoft Entra身份验证的客户端和管理库接受来自此库的凭据。 有关使用这些库的详细信息，请参阅文档（从版本页链接）。
已知问题
Azure AD B2C 支持
此库不支持 Azure AD B2C 服务。
有关其他未解决的问题，请参阅库的 GitHub 存储库。
提供反馈
如果遇到 bug 或有建议，请创建问题。
贡献
若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈