快速入门 - 在示例 Node.js Web 应用中登录用户并调用 Web API

适用于： 员工租户 外部租户（了解详细信息）

在本快速入门中，你将了解如何从外部租户中的 Node.js Web 应用程序登录用户和调用 Web API。 示例应用程序调用 .NET API。 此示例 Web 应用程序使用适用于 Node 的 Microsoft 身份验证库 (MSAL) 来处理身份验证。

先决条件

• 完成文章快速入门：在示例网络应用程序中登录用户的步骤和先决条件。 本文介绍如何使用示例 Node.js Web 应用使用户登录。
• 外部租户。 若要创建一个，请从以下方法中进行选择：
  • （推荐）使用 Microsoft Entra 外部 ID 扩展 直接在 Visual Studio Code 中设置外部租户。
  • 在 Microsoft Entra 管理中心创建新的外部租户。
• 在 Microsoft Entra 管理中心为您的 Web API 注册一个新的应用，并配置为仅限此组织目录中的帐户使用。 有关更多详细信息 ，请参阅注册应用程序 。 在应用程序 概述 页中记录以下值供以后使用：
  • 应用程序（客户端）ID
  • 目录（租户）ID
• Visual Studio Code 或其他代码编辑器。
• Node.js。
• .NET 7.0 或更高版本。

配置 API 范围和角色

通过注册 Web API，必须配置 API 范围，以定义客户端应用程序可以请求访问 Web API 的权限。 此外，需要设置应用角色来指定可供用户或应用程序使用的角色，并向 Web 应用授予必要的 API 权限，使其能够调用 Web API。

配置 API 范围

API 需要至少发布一个范围（也称为委托的权限），客户端应用才能成功获取用户的访问令牌。 若要发布范围，请执行以下步骤：

1. 从“应用注册”页中，选择创建的 API 应用程序 (ciam-ToDoList-api) 以打开其“概述”页。

2. 在“管理”下，选择“公开 API” 。

3. 在页面顶部的“应用程序 ID URI”旁边，选择“添加”链接以生成对此应用来说独一无二的 URI。

4. 接受建议的应用程序 ID URI，例如 api://{clientId}，然后选择“保存”。 当您的 Web 应用在请求 Web API 的访问令牌时，会将该 URI 添加为 API 每个定义范围的前缀。

5. 在“此 API 定义的范围”下选择“添加范围”。

6. 输入以下值，用于定义对 API 的读取访问权限，然后选择添加范围以保存更改：

   财产	价值
   范围名称	ToDoList.Read
   谁可以许可	仅管理员
   管理员同意显示名称	使用“ToDoListApi”读取用户待办事项列表
   管理员同意说明	允许应用使用“TodoListApi”读取用户的待办事项列表。
   国家	已启用

7. 再次选择添加范围，然后输入定义对 API 的读取和写入访问权限范围的以下值。 选择“添加作用域”，保存所做更改：

   财产	价值
   范围名称	ToDoList.ReadWrite
   谁可以许可	仅管理员
   管理员同意显示名称	使用“ToDoListApi”读写用户 ToDo 列表
   管理员同意说明	允许应用使用“ToDoListApi”读写用户的 ToDo 列表
   国家	已启用

详细了解 Web API 的发布权限时的最小特权原则。

配置应用角色

API 需要为应用程序发布至少一个应用角色（也称为 应用程序权限），客户端应用才能自行获取访问令牌。 应用程序权限是 API 想要使客户端应用程序能够成功地以自己的身份进行身份验证（无需让用户登录）时应发布的权限类型。 若要发布应用程序权限，请执行下列步骤：

1. 从“应用注册”页中，选择创建的应用程序（例如 ciam-ToDoList-api）以打开其“概述”页。

2. 在“管理”下，选择“应用角色”。

3. 选择“创建应用角色”，输入以下值，然后选择“应用”以保存更改：

   财产	价值
   显示名称	ToDoList.Read.All
   允许的成员类型	应用程序
   价值	ToDoList.Read.All
   DESCRIPTION	允许应用使用“TodoListApi”读写每个用户的待办事项列表
   要启用此应用角色吗？	保持选中状态

4. 再次选择“创建应用角色”，为第二个应用角色输入以下值，然后选择“应用”以保存更改：

   财产	价值
   显示名称	ToDoList.ReadWrite.All
   允许的成员类型	应用程序
   价值	ToDoList.ReadWrite.All
   DESCRIPTION	允许应用使用“ToDoListApi”读写每个用户的 ToDo 列表
   要启用此应用角色吗？	保持选中状态

配置可选声明

可以添加 idtyp 可选声明，以帮助 Web API 确定令牌是 应用 令牌还是 应用 + 用户 令牌。 尽管可以将 scp 和 roles 声明的组合用于同一目的，但使用 idtyp 声明仍是区分应用令牌和应用 + 用户令牌的最简单方法。 例如，当令牌为仅限应用的令牌时，此声明的值为 app。

使用 “配置可选声明 ”一文中的步骤将 idtyp 声明添加到访问令牌：

• 对于 令牌类型 ，请选择 “访问”。
• 从可选声明列表中，选择 idtyp。

向 Web 应用授予 API 权限

若要授予客户端应用 (ciam-client-app) API 权限，请执行以下步骤：

1. 在 应用注册 页中，选择创建的应用程序（如 ciam-client-app），以打开其 概述 页。

2. 在“管理”下，选择 API 权限。

3. 在“已配置权限”下，选择“添加权限”。

4. 选择“我的组织使用的 API”选项卡。

5. 在 API 列表中，选择 API（例如 ciam-ToDoList-api）。

6. 选择“委托的权限”选项。

7. 从权限列表中，选择“ToDoList.Read”、“ToDoList.ReadWrite”（必要时使用搜索框）。

8. 选择“添加权限”按钮。 此时，你已正确分配了权限。 但是，由于租户是客户的租户，因此消费者用户本身不能同意这些权限。 若要解决此问题，作为管理员的你必须代表租户中的所有用户同意这些权限：

   1. 选择“为<租户名称>授予管理员同意”，然后选择“是”。

   2. 选择“刷新”，然后验证两个范围的“状态”下是否均显示“已为 你的租户名称< 授予”。>

9. 从“配置的权限”列表中，选择“ToDoList.Read”和“ToDoList.ReadWrite”权限（一次选择一个），然后复制权限的完整 URI 供以后使用。 完整权限 URI 看起来类似于 api://{clientId}/{ToDoList.Read} 或 api://{clientId}/{ToDoList.ReadWrite}。

克隆或下载示例 Web 应用程序和 Web API

若要获取示例应用程序，可以从 GitHub 克隆它，也可以将其下载为 .zip 文件。

• 若要克隆示例，请打开命令提示符并导航到要创建项目的位置，并输入以下命令：

  git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

• 下载 .zip 文件。 将其解压缩到名称长度少于 260 个字符的文件路径。

安装项目依赖项

1. 打开控制台窗口，切换到包含 Node.js/Express 示例应用的目录：

   cd 2-Authorization\4-call-api-express\App
   

2. 运行以下命令以安装 Web 应用依赖项：

   npm install && npm update
   

配置示例 Web 应用和 API

若要在客户端 Web 应用示例中使用应用注册，请执行以下操作：

1. 在代码编辑器中打开 App\authConfig.js 文件。

2. 查找占位符：

   • Enter_the_Application_Id_Here 并将其替换为之前注册的客户端应用的应用程序（客户端）ID。 客户端应用是在先决条件中注册的。
   • Enter_the_Tenant_Subdomain_Here 并将其替换为 Directory （tenant） 子域。 例如，如果租户主域名是 contoso.onmicrosoft.com，请使用 contoso。 如果没有租户名称，请了解如何读取租户详细信息。
   • 查找 Enter_the_Client_Secret_Here 并将其替换为之前复制的应用机密值。
   • 查找 Enter_the_Web_Api_Application_Id_Here 并将其替换为你之前作为先决条件的一部分复制的 Web API 的应用程序（客户端）ID。

若要在 Web API 示例中使用应用注册，请执行以下操作：

1. 在代码编辑器中打开 API\ToDoListAPI\appsettings.json 文件。

2. 查找占位符：

   • 查找 Enter_the_Application_Id_Here 并将其替换为复制的 Web API 的应用程序（客户端）ID。 Web API 应用是您之前根据先决条件注册的应用程序之一。
   • 查找 Enter_the_Tenant_Id_Here 并将其替换为之前复制的目录（租户）ID。
   • Enter_the_Tenant_Subdomain_Here 并将其替换为 Directory （tenant） 子域。 例如，如果租户主域名是 contoso.onmicrosoft.com，请使用 contoso。 如果没有租户名称，请了解如何读取租户详细信息。

运行并测试示例 Web 应用和 API

1. 打开控制台窗口，然后使用以下命令运行 Web API：

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. 使用以下命令运行 Web 应用客户端：

   cd 2-Authorization\4-call-api-express\App
   npm install
   npm start
   

3. 打开浏览器，然后转到 http://localhost:3000.

4. 选择“登录”按钮。 系统会提示你登录。

   

5. 在登录页上，键入你的“电子邮件地址”，选择“下一步”，键入你的“密码”，然后选择“登录”。 如果没有帐户，请选择“无帐户? 创建一个”链接，以启动注册流。

6. 如果选择注册选项，则在填写电子邮件、一次性密码、新密码和更多帐户详细信息后，你就完成了整个注册流程。 你会看到类似于以下屏幕截图的页面。 如果选择登录选项，则会看到类似的页面。

   

调用 API

1. 若要调用 API，请选择“查看 todolist”链接。 你会看到类似于以下屏幕截图的页面。

   

2. 通过创建和删除项来操作待办事项列表。

工作原理

每次查看、添加或删除任务时，都会触发 API 调用。 每次触发 API 调用时，客户端 Web 应用都会获取一个具有调用 API 终结点所需权限（范围）的访问令牌。 例如，若要读取任务，客户端 Web 应用必须获取一个具有 ToDoList.Read 权限/范围的访问令牌。

Web API 终结点需要检查客户端应用提供的访问权限或范围是否有效。 如果访问令牌有效，则终结点会响应 HTTP 请求，否则会以“401 Unauthorized”HTTP 错误进行响应。

相关内容

• 教程：保护在外部租户中注册的 ASP.NET Core Web API。