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

用于中转身份验证的 Azure 标识插件

项目
11/08/2024

此包为用于 JavaScript 的 Azure 标识库（@azure/identity）提供了一个插件，该插件允许使用身份验证代理（例如 WAM）。

身份验证代理是在用户计算机上运行的应用程序，用于管理连接的帐户的身份验证握手和令牌维护。目前仅支持 Windows 身份验证代理 Web 帐户管理器（WAM）。

源代码 | 示例 | API 参考文档 |[Microsoft Entra ID 文档]（https://learn.microsoft.com/entra/identity/）

开始

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

先决条件

Azure 订阅。

安装包

此包旨在与 Azure Identity for JavaScript 一起使用。使用 npm安装 @azure/identity 和此包：

npm install --save @azure/identity
npm install --save @azure/identity-broker

支持的环境

适用于 JavaScript 的 Azure 标识插件支持从 v18 开始的稳定（甚至编号）版本的 Node.js。虽然插件可以在其他 Node.js 版本中运行，但不能保证任何支持。 @azure/identity-broker 不支持浏览器环境。

关键概念

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

父窗口句柄

通过 InteractiveBrowserCredential向中转站进行身份验证时，需要父窗口句柄来确保在请求窗口中正确显示身份验证对话框。在设备上的图形用户界面上下文中，窗口句柄是操作系统分配给每个窗口的唯一标识符。对于 Windows 操作系统，此句柄是一个整数值，用作对特定窗口的引用。

Microsoft 帐户（MSA）直通

Microsoft帐户（MSA）是由用户访问Microsoft服务的个人帐户。 MSA 直通是一种旧配置，使用户能够获取通常不接受 MSA 登录的资源的令牌。此功能仅适用于第一方应用程序。使用配置为使用 MSA 直通的应用程序进行身份验证的用户可将 legacyEnableMsaPassthrough 设置为 InteractiveBrowserCredentialNodeOptions.brokerOptions 内的 true，以允许 WAM 列出这些个人帐户。

重定向 URI

Microsoft Entra 应用程序依赖于重定向 URI 来确定在用户登录后发送身份验证响应的位置。若要通过 WAM 启用中转身份验证，应将匹配以下模式的重定向 URI 注册到应用程序：

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure 标识插件

自 @azure/identity 版本 2.0.0 起，适用于 JavaScript 的标识客户端库包括插件 API。此包（@azure/identity-broker）将从 @azure/identity 包中将插件对象作为参数传递给顶级 useIdentityPlugin 函数。在程序中启用本机中转站，如下所示：

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

调用 useIdentityPlugin后，本机代理插件将注册到 @azure/identity 包，并且将在支持 WAM 代理身份验证的 InteractiveBrowserCredential 上提供。此凭据在构造函数选项中 brokerOptions。

例子

注册插件后，可以通过将 enabled 属性设置为 true 传递给凭据构造函数的 brokerOptions 来启用 WAM 代理身份验证。在下面的示例中，我们使用 InteractiveBrowserCredential。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

有关使用 Electron 应用检索窗口句柄的完整示例，请参阅此示例。

当 useDefaultBrokerAccount 选项设置为 true时，凭据将尝试以无提示方式使用默认代理帐户。如果使用默认帐户失败，凭据将回退到交互式身份验证。

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

故障排除

有关如何诊断各种故障方案的详细信息，请参阅 Azure 标识 [故障排除指南][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] 。

伐木

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以通过在 @azure/logger中调用 setLogLevel 在运行时启用日志记录：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

后续步骤

提供反馈

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

贡献

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

通过