你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 JavaScript 的 Azure 标识客户端库 - 版本 4.5.0
Azure 标识库通过一组方便的 TokenCredential 实现提供 Microsoft Entra ID（以前为 Azure Active Directory） 令牌身份验证。
有关各种凭据的示例，请参阅 Azure 标识示例页。
关键链接：
开始
当前支持的环境
- LTS 版本的 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 的。 虽然 @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）。 请考虑在以下方案中使用 MSAL.js：
- 希望完全控制身份验证协议及其配置的开发人员。
- 我们的凭据类型旨在与 Azure SDK 客户端配合使用，这些客户端具有在核心 HTTP 层处理的智能缓存和令牌刷新。 如果你发现自己必须直接使用
getToken，则可以从使用 MSAL.js 来更好地控制身份验证流和令牌缓存。
可以通过以下链接阅读详细信息：
- 我们在 Azure 标识示例 页上描绘了
@azure/identity的一些高级用例。
对于浏览器中的高级身份验证工作流，我们提供了一个部分，其中展示了如何使用 @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 的依赖项并启用它。 请参阅 插件。
在浏览器中对客户端进行身份验证
为了在 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 托管环境中使用的凭据与本地开发中使用的凭据组合在一起，从而简化了身份验证，同时开发部署到 Azure 的应用。 有关详细信息，请参阅 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值跨会话保留，这意味着只要缓存令牌可用，就不需要重复交互式登录流。
例子
使用 DefaultAzureCredential 进行身份验证
此示例演示如何使用 DefaultAzureCredential从 @azure/keyvault-keys 客户端库对 KeyClient 进行身份验证。
import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";
// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// 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 使用户能够合并多个凭据实例来定义自定义凭据链。 此示例演示如何创建一个尝试使用两个不同配置 ClientSecretCredential实例进行身份验证的 ChainedTokenCredential，然后通过 @azure/keyvault-keys对 KeyClient 进行身份验证：
import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";
// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// 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
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 { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";
const credential = new ClientSecretCredential(
"<YOUR_TENANT_ID>",
"<YOUR_CLIENT_ID>",
"<YOUR_CLIENT_SECRET>",
{
authorityHost: AzureAuthorityHosts.AzureGovernment,
},
);
作为指定 authorityHost 参数的替代方法，还可以将 AZURE_AUTHORITY_HOST 环境变量设置为云颁发机构的 URL。 将多个凭据配置为向同一云进行身份验证或部署的环境需要定义目标云时，此方法非常有用：
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
为了方便起见，AzureAuthorityHosts 枚举定义了已知云的颁发机构;但是，如果云的颁发机构未在 AzureAuthorityHosts中列出，则可以将任何有效的颁发机构 URL 作为字符串参数传递。 例如：
import { ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
"<YOUR_TENANT_ID>",
"<YOUR_CLIENT_ID>",
"<YOUR_CLIENT_SECRET>",
{
authorityHost: "https://login.partner.microsoftonline.cn",
},
);
并非所有凭据都需要此配置。 通过开发工具（如 AzureCliCredential）进行身份验证的凭据使用该工具的配置。 同样，VisualStudioCodeCredential 接受 authorityHost 参数，但默认为与 Visual Studio Code Azure：云 设置匹配的 authorityHost。
凭据类
凭据链
| 凭据 | 用法 | 例 |
|---|---|---|
DefaultAzureCredential |
提供简化的身份验证体验，以便快速开始在 Azure 中运行应用程序。 | 示例 |
ChainedTokenCredential |
允许用户定义组成多个凭据的自定义身份验证流。 | 示例 |
对 Azure 托管的应用程序进行身份验证
| 凭据 | 用法 | 例 |
|---|---|---|
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_SEND_CERTIFICATE_CHAIN |
（可选） 在 x5c 标头中发送证书链以支持使用者名称/基于颁发者的身份验证 |
用户名和密码
| 变量名称 | 价值 |
|---|---|
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 存储库。
提供反馈
贡献
若要参与此库，请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。
