Azure Identity plugin for brokered authentication

该软件包为 JavaScript 的 Azure Identity 库（@azure/identity）提供了插件，使可以使用如 WAM 等认证代理。

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

源代码 | Samples | API 参考文档 | Microsoft Entra ID 文档 documentation

开始

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

useIdentityPlugin(nativeBrokerPlugin);

先决条件

• Azure订阅。

注意：对于使用 @azure/identity-broker的本地开发，您可能需要安装其他工具。 node-gyp 用于编译用于访问系统 API 的 插件 。 安装要求列在 node-gyp 自述文件中。

在 Linux 上，该库使用 libsecret ，因此您可能需要安装它。 根据您的发行版，您需要运行以下命令：

• Debian/Ubuntu： sudo apt-get install libsecret-1-dev
• 基于红帽： sudo yum install libsecret-devel
• 拱形Linux： sudo pacman -S libsecret

安装包

该软件包设计用于与 Azure Identity for JavaScript 配合使用。 使用 @azure/identity安装 npm 和此包：

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

支持的环境

Azure Identity JavaScript 插件支持从 v20 起稳定（偶数编号）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 设置为 true 内的 InteractiveBrowserCredentialNodeOptions.brokerOptions，以允许 WAM 列出这些个人帐户。

重定向 URI

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

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

Azure Identity plugins

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

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。

注释：自@azure/identity版本4.11.0-beta.1起，DefaultAzureCredential支持通过Windows网页账户管理器登录。 在程序中启用本机中转站，如下所示：

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

例子

注册插件后，可以通过将 brokerOptions 属性设置为 enabled 传递给凭据构造函数的 true 来启用 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 应用获取窗口句柄的完整示例，请参见 this sample。

使用默认帐户进行登录

当 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身份 troubleshooting guide，了解如何诊断各种故障场景。

伐木

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

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

setLogLevel("info");

后续步骤

提供反馈

如果你遇到漏洞或有建议，请open a issue。

贡献

如果你想为该库贡献内容，请参阅 贡献指南，了解如何构建和测试代码。