Compartir a través de

在受保护的 Web API 中公开作用域

本文介绍如何为受保护的 Web API 向应用程序添加范围。

先决条件

范围和应用程序 ID URI

范围通常采用 resourceURI/scopeName 格式。 对于 Microsoft Graph，范围具有快捷方式。 例如，User.Read 是 https://microsoftgraph.chinacloudapi.cn/user.read 的快捷方式。

在应用注册过程中，请定义以下参数：

  • 资源 URI
  • 一个或多个范围
  • 一个或多个应用角色

默认情况下，应用程序注册门户建议使用资源 URI api://{clientId}。 此 URI 是唯一的，但用户无法识别它。 如果更改 URI，请确保新值是唯一的。 应用程序注册门户可确保使用 配置的发布者域。

对于客户端应用程序，范围将显示为委托的权限，应用角色将显示为 Web API 的应用程序权限。

范围还会出现在向应用用户显示的许可窗口中。 因此，请提供描述范围的响应字符串：

  • 用户看到的内容。
  • 可授予管理员许可的租户管理员看到的内容。

用户无法同意应用角色（因为它们由代表自己调用 Web API 的应用程序使用）。 租户管理员需要同意使用您的 Web API 的客户端应用程序，因该 API 公开了应用角色。 有关详细信息，请参阅管理员同意。

公开委托的权限（范围）

若要公开委托的权限或范围，请按照将应用程序配置为公开 Web API 中的步骤操作。

如果按照这一系列文章所述的 Web API 方案操作，请使用以下设置：

  • 应用程序 ID URI：如果系统提示，请接受建议的应用程序 ID URI (api://clientId<)
  • 范围名称：access_as_user
  • 谁能同意：管理员和用户
  • 管理员同意显示名称：以用户身份访问 TodoListService
  • 管理员同意说明：以用户身份访问 TodoListService Web API
  • 用户同意显示名称：以用户身份访问 TodoListService
  • 用户同意说明：以用户身份访问 TodoListService Web API
  • 状态：已启用

小窍门

对于 应用程序 ID URI，可以将它设置为 API 的物理颁发机构，例如 https://microsoftgraph.chinacloudapi.cn。 当需要调用的 API 的 URL 已知时，这非常有用。

如果 Web API 由服务或守护程序应用调用

如果 API 应由守护程序、服务或其他非交互式（由人进行的）应用程序访问，则公开应用程序权限而不是委托权限。 由于守护程序和服务类型应用程序以无人参与方式运行并使用自己的标识进行身份验证，因此没有用户对其权限进行“委托”。

公开应用程序权限（应用角色）

若要公开应用程序权限，请按照向应用添加应用角色中的步骤操作。

在“允许的成员类型”下的“创建应用角色”窗格中，选择“应用程序”。 或者，使用“应用程序清单编辑器”添加角色，如本文所述。

将访问令牌限制为供特定客户端应用使用

应用角色是应用程序开发人员用来公开其应用权限的机制。 Web API 的代码应检查从调用方收到的访问令牌中的应用角色。

若要添加另一层安全性，Microsoft Entra 租户管理员可以配置其租户，以便 Microsoft 身份平台 仅 向租户管理员批准用于 API 访问的客户端应用颁发安全令牌。

若要通过将令牌颁发对象限制为已被分配应用角色的客户端应用来提高安全性，请执行以下操作：

  1. 在 Microsoft Entra 管理中心中，在 Entra ID>应用注册下选择你的应用。
  2. 在应用程序的“概述”页上的“概要”中，查找并选择其“本地目录中的托管应用程序”链接，以导航到其“企业应用程序概述”页。
  3. 在 管理 下，选择 属性。
  4. 将“需要分配?”设置为“是”。
  5. 选择“保存”。

Microsoft Entra ID 现在将检查客户端应用程序的应用角色分配，这些客户端应用程序请求 Web API 的访问令牌。 如果客户端应用尚未分配有任何应用角色，则 Microsoft Entra ID 会将类似于 _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_ 的错误消息返回给客户端。

警告

请勿在应用程序的代码中使用 AADSTS 错误代码或其消息字符串作为文本。 Microsoft Entra ID 返回的“AADSTS”错误代码和错误消息字符串并不是不可变的，可能会在您不知情的情况下随时被 Microsoft 更改。 如果根据 AADSTS 代码的值或其消息字符串的值在代码中做出分支决策，则会导致应用程序的功能和稳定性出现风险。

后续步骤

本系列中的下一篇文章是应用代码配置。