你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 JavaScript 的 Azure 标识客户端库 - 版本 4.2.1
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 大多数凭据类型都使用 适用于 JavaScript 的 Microsoft 身份验证库 (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 开发人员 CLI 进行身份验证
在 IDE 外部编码的开发人员也可以使用 [Azure 开发人员 CLI][azure_developer_cli] 进行身份验证。 然后，使用 DefaultAzureCredential 或 AzureDeveloperCliCredential 的应用程序可以在本地运行时使用此帐户对其应用程序中的调用进行身份验证。
若要使用 [Azure 开发人员 CLI][azure_developer_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 命令将使用设备代码身份验证流。 用户还可以通过指定 --use-device-code 参数来强制 Azure CLI 使用设备代码流，而不是启动浏览器。
通过 Azure PowerShell 进行身份验证
使用 AzurePowerShellCredential的应用程序，无论是直接还是通过 DefaultAzureCredential，都可以使用连接到 Azure PowerShell 的帐户在本地运行时对应用程序中的调用进行身份验证。
若要使用 Azure PowerShell 进行身份验证，用户可以运行 Connect-AzAccount cmdlet。 默认情况下，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，可以将其设置为使用重定向或弹出窗口来完成身份验证流。 必须先在 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 将按顺序尝试通过以下机制进行身份验证：
-
环境 -
DefaultAzureCredential将读取通过 环境变量 指定的帐户信息，并使用它来进行身份验证。 -
工作负载标识 - 如果应用程序部署到启用了托管标识的 Azure Kubernetes 服务，
DefaultAzureCredential将使用它进行身份验证。 -
托管标识 - 如果应用程序部署到启用了托管标识的 Azure 主机，
DefaultAzureCredential将使用该帐户进行身份验证。 -
Azure CLI - 如果开发人员已通过 Azure CLI
az login命令对帐户进行身份验证，DefaultAzureCredential则 将使用该帐户进行身份验证。 -
Azure PowerShell - 如果开发人员已使用 Azure PowerShell 模块
Connect-AzAccount命令进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。 -
Azure 开发人员 CLI - 如果开发人员已通过 Azure 开发人员 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 工作负载 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) 保护的资源。 可以使用 API 启用此功能GetTokenOptions.enableCae(boolean)。 开发人员凭据不支持 CAE。
令牌缓存
令牌缓存是 Azure 标识库提供的一项功能，它允许应用：
- 在内存中缓存令牌 (默认) 和磁盘上的令牌 (选择加入) 。
- 提高复原能力和性能。
- 减少对 Microsoft Entra ID 发出的请求数以获取访问令牌。
Azure 标识库提供内存中缓存和永久性磁盘缓存。 有关更多详细信息，请参阅 令牌缓存文档。
中介身份验证
身份验证代理是在用户计算机上运行并管理已连接帐户的身份验证握手和令牌维护的应用程序。 目前，仅支持 Windows Web 帐户管理器 (WAM) 。 若要启用支持，请使用 @azure/identity-broker 包。 有关使用 WAM 进行身份验证的详细信息，请参阅 代理插件文档。
故障排除
有关故障排除的帮助，请参阅 故障排除指南。
后续步骤
阅读文档
可以在文档站点上找到此库的 API 文档。
客户端库支持
支持 Microsoft Entra 身份验证的 Azure SDK 发布页上 列出的客户端和管理库接受来自此库的凭据。 有关使用这些库的详细信息，请参阅从发布页链接的文档。
已知问题
Azure AD B2C 支持
此库不支持 Azure AD B2C 服务。
有关其他未解决的问题，请参阅库的 GitHub 存储库。
提供反馈
如果遇到 bug 或有建议，请创建问题。
贡献
若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈