你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
用于中转身份验证的 Azure 标识插件
此包为适用于 JavaScript (@azure/identity
) 的 Azure 标识库提供了一个插件,该插件支持使用身份验证代理(如 WAM)。
身份验证代理是在用户计算机上运行的应用程序,用于管理已连接帐户的身份验证握手和令牌维护。 目前,仅支持 Windows 身份验证代理 Web 帐户管理器 (WAM) 。
源代码 | 样品 | API 参考文档 |[Microsoft Entra ID 文档] (https://video2.skills-academy.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 传递的应用程序进行身份验证的用户可以将 设置为 legacyEnableMsaPassthrough
true
内部 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
。
示例
注册插件后,可以通过传递 brokerOptions
enabled
并将 属性设置为 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 或有建议,请创建问题。
贡献
若要参与此库,请参阅 参与指南 ,详细了解如何生成和测试代码。