Microsoft 身份验证库 (MSAL) Node 支持从本机令牌中转站获取令牌。 使用本机代理时，刷新令牌会绑定到获取这些令牌的设备，msal-node 或该应用程序都无法访问这些令牌。 这可提供更高级别的安全性，而仅靠 msal-node 无法实现这一点。
本文介绍如何配置Windows代理、设置所有权证明和了解代理特定的行为。
代理支持在以下平台上可用：
| Platform | Broker | Documentation |
|---|---|---|
| Windows | Web 帐户管理器 (WAM) | Windows 中转站（本文） |
| macOS | Microsoft Enterprise SSO 插件（公司门户） | macOS 代理 |
| Linux | 适用于 Linux 的Microsoft单一登录 | Linux 代理 |
什么是中转站
身份验证代理是在用户计算机上运行的组件，用于管理连接的帐户的身份验证握手和令牌生命周期。 在Windows，此角色由 Web 客户经理（WAM）执行。 主要优势包括：
- 增强的安全性。 无需更改应用代码即可通过 OS 或中转站更新提供安全改进。 刷新令牌与设备绑定，并受到保护以防止被窃取。
- 功能支持。 无需额外的样板代码，即可访问丰富的操作系统功能，例如 Windows Hello、Microsoft Entra 条件访问策略和 FIDO 安全密钥。
- 系统集成。 应用程序插入内置帐户选取器，允许用户快速选择现有帐户，而不是重新输入凭据。
- 令牌保护。 中转站确保刷新令牌与设备绑定，并使应用程序能够获取基于所有权证明的访问令牌。
支持的体系结构
- Windows：x64、x86、ARM64
先决条件
- Node.js 18 或更高版本
- 安装
@azure/msal-node-extensions作为依赖项 - 在应用注册中注册代理的重定向 URI。 有关所需值，请参阅 重定向 URI。
重定向 URI
在 Azure 门户中的移动和桌面应用程序平台下注册以下重定向 URI：
ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>
用你的应用的客户端 ID 替换 <your-client-id>。
启用功能
启用令牌代理只需要一个配置参数。 在代理配置中传入一个 NativeBrokerPlugin 实例：
import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";
const msalConfig: Configuration = {
auth: {
clientId: "your-client-id",
},
broker: {
nativeBrokerPlugin: new NativeBrokerPlugin(),
},
};
const pca = new PublicClientApplication(msalConfig);
注释
在发生故障时，msal-node不会回退到非中转站处理的流程。 仅在支持代理流程的环境中启用该流程，以避免意外失败。
可以在 auth-code-cli-brokered-app 示例中找到一个工作示例。
窗口父级
若要在调用应用程序上显示身份验证提示并阻止进一步交互，请向 API 提供应用程序的窗口句柄 acquireTokenInteractive 。
对于 CLI 应用，系统会在底层尽力尝试查找窗口句柄，但这种方式并不可靠。
如果您使用 Electron，请使用 getNativeWindowHandle API，并将结果传入 acquireTokenInteractive：
import { BrowserWindow } from "electron";
const win = new BrowserWindow();
const pca = new PublicClientApplication(msalConfig);
pca.acquireTokenInteractive({
windowHandle: win.getNativeWindowHandle(),
});
所有权证明
通过本机中转站获取令牌时，支持访问令牌所有权证明 (PoP)。 若要请求 PoP 令牌，请将以下属性添加到传递给 acquireTokenInteractive 或 acquireTokenSilent 的请求对象中：
AT PoP 请求参数
| 名称 | Description | 必选 |
|---|---|---|
authenticationScheme |
指示 MSAL 是否应获取 Bearer 令牌还是 PoP 令牌。 默认值为 Bearer。 |
必填 |
resourceRequestMethod |
将使用已签名令牌（GET、POST、PUT 等）的请求所用 HTTP 方法的全大写名称 |
必填 |
resourceRequestUri |
要为其颁发访问令牌的受保护资源的 URL | 必填 |
shrNonce |
一个服务器生成的签名时间戳，该时间戳是 Base64URL 编码为字符串。 该随机数用于缓解时钟偏差和按时间顺序查看攻击，此类攻击旨在实现 PoP 令牌的预生成。 | 可选 |
用法示例
此示例通过设置身份验证方案和已签名的 HTTP 请求属性来请求所有权证明令牌：
import { PublicClientApplication, Configuration, AuthenticationScheme } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";
const msalConfig: Configuration = {
auth: {
clientId: "your-client-id",
},
broker: {
nativeBrokerPlugin: new NativeBrokerPlugin(),
},
};
const pca = new PublicClientApplication(msalConfig);
const popTokenRequest = {
scopes: ["User.Read"],
authenticationScheme: AuthenticationScheme.POP,
resourceRequestMethod: "POST",
resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER",
};
pca.acquireTokenInteractive(popTokenRequest);
pca.acquireTokenSilent(popTokenRequest);
注释
访问令牌所有权证明仅通过本机中转站流程支持，在非中转站流程中不可用。
使用 Windows 代理时的差异
通过本机中转站获取令牌时，有几个行为可能会有所不同：
-
acquireTokenSilent调用中的forceRefresh参数不受支持。 无论此标志设置为何值，你都可能从中转站收到一个缓存令牌。 - 如果中转站需要提示用户进行交互，系统会打开系统提示。 这会更改用户体验（UX），因为身份验证不会在浏览器窗口中发生。
- 访问令牌所有权证明受中转站支持，但不受非中转站支持。