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

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

项目
06/12/2024

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

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

源代码 | 样品 | API 参考文档 |[Microsoft Entra ID 文档] (https://learn.microsoft.com/entra/identity/)

入门

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

useIdentityPlugin(nativeBrokerPlugin);

先决条件

一个 Azure 订阅。

安装包

此包旨在与适用于 JavaScript 的 Azure 标识一起使用。 @azure/identity使用 npm安装和此包：

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，我们建议你先阅读 Using @azure/identity with Microsoft Entra ID 。本文档将让你更深入地了解平台以及如何正确配置 Azure 帐户。

父窗口句柄

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

Microsoft 帐户 (MSA) 直通

microsoft 帐户 (MSA) 是用户为访问 Microsoft 服务而创建的个人帐户。 MSA 直通是一种旧配置，使用户能够获取通常不接受 MSA 登录的资源的令牌。此功能仅适用于第一方应用程序。使用配置为使用 MSA 传递的应用程序进行身份验证的用户可以将设置为 legacyEnableMsaPassthroughtrue 内部 InteractiveBrowserCredentialNodeOptions.brokerOptions ，以允许 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 { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
  },
});

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

示例

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

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

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      useDefaultBrokerAccount: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

  // 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), "...");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

故障排除

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

日志记录

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

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

setLogLevel("info");

后续步骤

提供反馈

如果遇到 bug 或有建议，请创建问题。

贡献

若要参与此库，请参阅参与指南，详细了解如何生成和测试代码。

曝光数

通过