通过

在示例 Node.js Web 应用程序中登录用户并调用 API

  • 项目

本指南使用示例 Node.js Web 应用程序来演示如何添加身份验证和授权。 示例应用程序将用户登录到 Node.js Web 应用，然后调用 .NET API。 使用外部租户详细信息启用身份验证和授权。 此示例 Web 应用程序使用适用于 Node 的 Microsoft 身份验证库 (MSAL) 来处理身份验证。

在本文中，你将完成以下任务：

  • 在 Microsoft Entra 管理中心注册和配置 Web API。

  • 在 Microsoft Entra 管理中心注册和配置客户端 Web 应用程序。

  • 在 Microsoft Entra 管理中心创建注册和登录用户流，然后将客户端 Web 应用与其关联。

  • 更新示例 Node Web 应用程序和 ASP.NET Web API，以使用你的外部租户详细信息。

  • 运行并测试示例 Web 应用程序和 API。

先决条件

注册 Web 应用程序和 Web API

在此步骤中，你将创建 Web 和 Web API 应用程序注册，并指定 Web API 的范围。

注册 Web API 应用程序

  1. 至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。

  2. 如果你有权访问多个租户，请使用顶部菜单中的“设置”图标 ，通过“目录 + 订阅”菜单切换到你的外部租户。

  3. 浏览到“标识”>“应用程序”>“应用注册”。

  4. 选择“+ 新建注册”。

  5. 在出现的“注册应用程序”页面中，输入应用程序的注册信息：

    1. 在“名称”部分中，输入将向应用用户显示的有意义的应用程序名称，例如“ciam-ToDoList-api”。

    2. 在“支持的帐户类型”下，选择“仅此组织目录中的帐户” 。

  6. 选择“注册”以创建应用程序。

  7. 注册完成后，将显示应用程序的“概述”窗格。 记录要在应用程序源代码中使用的目录（租户）ID 和应用程序（客户端）ID。

配置 API 范围

此 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 列表
    状态 已启用

  8. 在“管理”下，选择“清单”以打开 API 清单编辑器。

  9. 将 accessTokenAcceptedVersion 属性设置为 2。

  10. 选择“保存”。

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

配置应用角色

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

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

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

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

    属性 值
    显示名称 ToDoList.Read.All
    允许的成员类型 应用程序
    值 ToDoList.Read.All
    说明 允许应用使用“TodoListApi”读写每个用户的待办事项列表

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

    属性 值
    显示名称 ToDoList.ReadWrite.All
    允许的成员类型 应用程序
    值 ToDoList.ReadWrite.All
    说明 允许应用使用“ToDoListApi”读写每个用户的 ToDo 列表

配置可选声明

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

注册 Web 应用

若要使应用程序能够让用户通过 Microsoft Entra 登录，必须让 Microsoft Entra 外部 ID 能够感知你创建的应用程序。 应用注册会在应用与 Microsoft Entra 之间建立信任关系。 注册应用程序时，外部 ID 会生成一个称为“应用程序（客户端）ID”的唯一标识符，该值用于在创建身份验证请求时标识应用。

以下步骤演示如何在 Microsoft Entra 管理中心注册应用：

  1. 至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。

  2. 如果你有权访问多个租户，请使用顶部菜单中的“设置”图标 ，通过“目录 + 订阅”菜单切换到你的外部租户。

  3. 浏览到“标识”>“应用程序”>“应用注册”。

  4. 选择“+ 新建注册”。

  5. 在显示的“注册应用程序”页中；

    1. 输入一个向应用用户显示的、有意义的应用程序名称，例如 ciam-client-app。
    2. 在“支持的帐户类型”下，选择“仅此组织目录中的帐户” 。

  6. 选择“注册”。

  7. 成功注册后，会显示应用程序的“概述”窗格。 记录要在应用程序源代码中使用的应用程序（客户端）ID。

若要为应用注册指定应用类型，请执行以下步骤：

  1. 在“管理”下，选择“身份验证”。
  2. 在“平台配置”页上，选择“添加平台”，然后选择“Web”选项。
  3. 对于“重定向 URI”，请输入 http://localhost:3000/auth/redirect。
  4. 选择“配置”以保存更改。

创建客户端机密

为注册的应用创建客户端机密。 应用程序在请求令牌时使用客户端密码来证明其身份。

  1. 从“应用注册”页中，选择创建的应用程序（例如 ciam-client-app）以打开其“概述”页。
  2. 在“管理”下，选择“证书和机密”。
  3. 选择“新建客户端机密”。
  4. 在“说明”框中输入对客户端密码的说明（如 ciam 应用客户端密码）。
  5. 在“过期时间”下，选择密码的有效期（根据组织的安全规则），然后选择“添加”。
  6. 记下机密的“值”。 在稍后的步骤中将使用此值进行配置。 离开“证书和机密”后，机密值不会再次显示，并且无法以任何方式检索。 请确保记录它。

向 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}。

创建用户流

按照这些步骤创建可供客户用于登录或注册应用程序的用户流。

  1. 至少以外部 ID 用户流管理员身份登录到 Microsoft Entra 管理中心。

  2. 如果你有权访问多个租户，请使用顶部菜单中的“设置”图标 ，通过“目录 + 订阅”菜单切换到你的外部租户。

  3. 浏览到“标识”>“外部标识”>“用户流”。

  4. 选择“+ 新建用户流”。

  5. 在“创建”页上执行以下操作：

    1. 为用户流输入名称，例如 SignInSignUpSample。

    2. 在“标识提供者”列表中，选择“电子邮件帐户”。 此标识提供者使用户能够使用其电子邮件地址登录或注册。

      注意

      只有在设置了与额外的标识提供者的联合身份验证之后，才会在此处列出这些标识提供者。 例如，如果设置了与 Google 或 Facebook 的联合身份验证，则能够在此处选择这些额外的标识提供者。

    3. 在“电子邮件帐户”下，可以选择两个选项之一。 对于本教程，请选择“电子邮件和密码”。

      • 电子邮件和密码：使新用户能够使用电子邮件地址作为登录名称并使用密码作为其第一重身份验证凭据进行注册和登录。
      • 电子邮件一次性密码：使新用户能够使用电子邮件地址作为登录名称并使用电子邮件一次性密码作为其第一重身份验证凭据进行注册和登录。 只有在租户级别启用电子邮件一次性密码（“所有标识提供者”>“电子邮件一次性密码”），才能在用户流级别使用此选项。

    4. 在“用户属性”下，选择要在用户注册时收集的用户属性。 选择“显示更多内容”即可选择“国家/地区”、“显示名称”和“邮政编码”的属性和声明。 选择“确定” 。 （系统仅在用户首次注册时提示输入属性。）

  6. 选择“创建” 。 此时，新的用户流将显示在“用户流”列表中。 如果需要，请刷新页面。

若要启用自助式密码重置，请使用启用自助式密码重置一文中的步骤。

将 Web 应用程序与用户流相关联

尽管许多应用程序可与用户流相关联，但单个应用程序只能与一个用户流相关联。 用户流允许为特定应用程序配置用户体验。 例如，可以配置一个要求用户使用电子邮件地址登录或注册的用户流。

  1. 在边栏菜单中选择“标识”。

  2. 依次选择“外部标识”和“用户流”。

  3. 在“用户流”页中，选择之前创建的用户流名称，例如 SignInSignUpSample。

  4. 在“使用”下，选择“应用程序”。

  5. 选择“添加应用程序”。

  6. 从列表中选择应用程序（如 ciam-client-app），或使用搜索框查找应用程序，然后将其选中。

  7. 选择“选择”。

克隆或下载示例 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 并将其替换为目录（租户）子域。 例如，如果租户主域为 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。
    • 查找 Enter_the_Tenant_Id_Here 并将其替换为之前复制的目录（租户）ID。
    • 查找 Enter_the_Tenant_Subdomain_Here 并将其替换为目录（租户）子域。 例如，如果租户主域为 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 start

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

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

    屏幕截图显示登录到 Node Web 应用。

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

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

    屏幕截图显示登录到 Node Web 应用并调用 API。

调用 API

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

    屏幕截图显示如何调用 API 来操作待办事项列表。

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

工作原理

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

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

相关内容