受保护的 Web API：应用注册

  • 项目

本文介绍适用于受保护 Web API 的应用注册详细信息。

有关注册应用程序的常用步骤，请参阅快速入门：将应用程序注册到 Microsoft 标识平台。

接受的令牌版本

Microsoft 标识平台可以发出 v1.0 令牌和 v2.0 令牌。 有关这些令牌的详细信息，请参阅访问令牌。

在 Azure 门户中创建 Web API 应用程序注册时，API 可以接受的令牌版本取决于你选择的“支持的帐户类型”。

  • 如果“支持的帐户类型”的值是任何组织目录中的帐户和个人 Microsoft 帐户（例如 Skype、Xbox、Outlook.com），则接受的令牌版本必须为 v2.0 。
  • 否则，已接受的令牌版本可以为 v1.0。

创建应用程序后，可以按以下步骤确定或更改接受的令牌版本：

  1. 在 Azure 门户中选择你的应用，然后选择“清单”。
  2. 在清单中找到 accessTokenAcceptedVersion 属性。
  3. 该值向 Microsoft Entra 指定 Web API 接受哪个令牌版本。
    • 如果值为 2，则 Web API 接受 v2.0 令牌。
    • 如果值为 null，则 Web API 接受 v1.0 令牌。
  4. 如果更改了令牌版本，请选择“保存”。

Web API 会指定它所接受的令牌版本。 当客户端从 Microsoft 标识平台请求 Web API 的令牌时，所获取的令牌会指示 Web API 接受哪个令牌版本。

无重定向 URI

Web API 不需注册重定向 URI，因为没有任何用户以交互方式登录。

公开的 API

特定于 Web API 的其他设置是公开的 API 和公开的范围或应用角色。

范围和应用程序 ID URI

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

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

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

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

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

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

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

用户不能同意应用程序角色（因为它们是由代表自己调用 Web API 的应用程序使用的）。 租户管理员将需要同意你的 Web 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://graph.microsoft.com。 当需要调用的 API 的 URL 已知时，这非常有用。

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

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

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

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

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

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

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

若要添加另一层安全性，Microsoft Entra 租户管理员可以将其租户配置为使 Microsoft 标识平台仅向已批准进行 API 访问的客户端应用颁发安全令牌。

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

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

Microsoft Entra ID 现在将检查客户端应用程序的应用角色分配，这些客户端应用程序请求 Web API 的访问令牌。 如果客户端应用尚未分配任何应用角色，Microsoft Entra ID 会将一条错误消息返回到客户端，该消息类似于“invalid_client: AADSTS501051: 应用程序 <应用程序名称> 未分配给 <Web API> 的角色”。

警告

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

后续步骤

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