快速入门:获取令牌并从 Node.js 控制台应用中调用 Microsoft Graph API
在本快速入门中,你将下载并运行一个代码示例,该示例演示 Node.js 控制台应用程序如何使用应用的标识获取访问令牌来调用 Microsoft Graph API 并在目录中显示用户列表。 代码示例演示无人参与的作业或 Windows 服务如何使用应用程序标识而不是用户标识运行。
本快速入门通过客户端凭据授权使用适用于 Node.js 的 Microsoft 身份验证库 (MSAL Node)。
先决条件
- Node.js
- Visual Studio Code 或其他代码编辑器
注册并下载示例应用程序
请按照以下步骤开始使用。
步骤 1:注册应用程序
提示
本文中的步骤可能因开始使用的门户而略有不同。
若要手动注册应用程序并将应用的注册信息添加到解决方案,请执行以下步骤:
- 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
- 浏览到“标识”>“应用程序”>“应用注册”。
- 选择“新注册”。
- 输入应用程序的名称(例如
msal-node-cli
)。 应用的用户可能会看到此名称,你稍后可对其进行更改。 - 选择“注册” 。
- 在“管理”下,选择“证书和机密”。
- 在“客户端机密”下,选择“新建客户端机密”,输入名称,然后选择“添加” 。 将机密值记录在安全的位置,以供在后面的步骤中使用。
- 在“管理”下,选择“API 权限”>“添加权限” 。 选择“Microsoft Graph”。
- 选择“应用程序权限”。
- 在“用户”节点下选择“User.Read.All”,然后选择“添加权限” 。
步骤 2:下载 Node.js 示例项目
步骤 3:配置 Node.js 示例项目
将 zip 文件提取到靠近磁盘根目录的本地文件夹,例如 C:/Azure-Samples。
编辑 .env,将字段
TENANT_ID
、CLIENT_ID
、CLIENT_SECRET
的值替换为以下代码片段:"TENANT_ID": "Enter_the_Tenant_Id_Here", "CLIENT_ID": "Enter_the_Application_Id_Here", "CLIENT_SECRET": "Enter_the_Client_Secret_Here"
其中:
Enter_the_Application_Id_Here
- 先前注册的应用程序的应用程序(客户端)ID。 在应用注册“概述”中找到此 ID。Enter_the_Tenant_Id_Here
- 将此值替换为租户 ID 或租户名称(例如 contoso.microsoft.com) 。 在应用注册“概述”中找到这些值。Enter_the_Client_Secret_Here
- 将此值替换为先前创建的客户端密码。 若要生成新密钥,请在应用注册设置中使用“证书和机密”。
在源代码中使用纯文本机密会增加应用程序的安全风险。 尽管本快速入门中的示例使用纯文本客户端密码,但这只是为了简单起见。 建议在机密客户端应用程序中使用证书凭据(而不是客户端密码),尤其是计划部署到生产环境的应用。
编辑 .env,将 Microsoft Entra ID 和 Microsoft Graph 终结点替换为以下值:
- 对于 Microsoft Entra 终结点,请将
Enter_the_Cloud_Instance_Id_Here
替换为https://login.partner.microsoftonline.cn
。 - 对于 Microsoft Graph 终结点,请将
Enter_the_Graph_Endpoint_Here
替换为https://microsoftgraph.chinacloudapi.cn/
。
- 对于 Microsoft Entra 终结点,请将
步骤 4:管理员同意
如果尝试在此时运行应用程序,则会收到“HTTP 403 - 禁止访问”错误:Insufficient privileges to complete the operation
。 之所以出现这种错误,是因为任何仅限应用的权限都需要管理员同意:必须由分配了至少“应用管理员”角色向应用授予同意。 根据自己的角色选择下面的一个选项:
管理员
如果已为你分配了至少为“应用管理员”角色,请转到 Azure 门户的“应用程序注册”中的“API 权限”页,并选择“为 {租户名称} 授予管理员同意”(其中,{租户名称} 是目录的名称)。
标准用户
如果你是租户的标准用户,你需要请求云应用程序管理员为你的应用程序授予管理员同意。 为此,请将以下 URL 提供给管理员:
https://login.partner.microsoftonline.cn/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here
其中:
Enter_the_Tenant_Id_Here
- 将此值替换为租户 ID 或租户名称(例如 contoso.microsoft.com)Enter_the_Application_Id_Here
- 是已注册应用程序的应用程序(客户端)ID。
步骤 5:运行应用程序
定位到命令提示符或控制台中示例的根文件夹(package.json
所在位置)。 在首次运行示例应用之前,需要安装示例应用所需的依赖项:
npm install
然后,通过命令提示符或控制台运行应用程序:
node . --op getUsers
应该会在控制台输出上看到一些 JSON 片段,表示 Microsoft Entra 目录中的用户列表。
关于代码
下面讨论了示例应用程序的一些重要方面。
MSAL Node
MSAL Node 是一个用于登录用户和请求令牌的库,此类令牌用于访问受 Microsoft 标识平台保护的 API。 如前所述,本快速入门通过应用程序权限请求令牌(使用应用程序自身的标识),而不是通过委托的权限。 此示例中使用的身份验证流称为 OAuth 2.0 客户端凭据流。 若要详细了解如何搭配使用 MSAL Node 和守护程序应用,请参阅方案:守护程序应用程序。
可通过运行以下 npm 命令安装 MSAL Node。
npm install @azure/msal-node --save
MSAL 初始化
可以通过添加以下代码,为 MSAL 添加引用:
const msal = require('@azure/msal-node');
然后,使用以下代码对 MSAL 进行初始化:
const msalConfig = {
auth: {
clientId: "Enter_the_Application_Id_Here",
authority: "https://login.partner.microsoftonline.cn/Enter_the_Tenant_Id_Here",
clientSecret: "Enter_the_Client_Secret_Here",
}
};
const cca = new msal.ConfidentialClientApplication(msalConfig);
其中: | 说明 |
---|---|
clientId |
是在 Azure 门户中注册的应用程序的应用程序(客户端) ID。 可以在 Azure 门户的应用的“概览”页中找到此值。 |
authority |
用户要进行身份验证的 STS 终结点。 对于公有云,通常为 https://login.partner.microsoftonline.cn/{tenant} ,其中 {tenant} 是租户名称或租户 ID。 |
clientSecret |
是在 Azure 门户中为应用程序创建的客户端机密。 |
有关详细信息,请参阅 ConfidentialClientApplication
的参考文档
请求令牌
若要通过应用的标识来请求令牌,请使用 acquireTokenByClientCredential
方法:
const tokenRequest = {
scopes: [ 'https://microsoftgraph.chinacloudapi.cn/.default' ],
};
const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);
其中: | 说明 |
---|---|
tokenRequest |
包含请求的范围。 对于机密客户端,这应该使用与 {Application ID URI}/.default 类似的格式,指示所请求的范围是在 Azure 门户的应用对象集中静态定义的范围(就 Microsoft Graph 来说,{Application ID URI} 指向 https://microsoftgraph.chinacloudapi.cn )。 对于自定义 Web API,{Application ID URI} 在 Azure 门户的“应用程序注册”的“公开 API”部分中定义。 |
tokenResponse |
响应包含所请求范围的访问令牌。 |
帮助和支持
如果需要帮助、需要报告问题,或者需要详细了解支持选项,请参阅面向开发人员的帮助和支持。
后续步骤
若要详细了解如何通过 MSAL Node 进行守护程序/控制台应用开发,请参阅教程: