通过

快速入门：配置应用程序以公开 Web API

  • 项目

本快速入门将向 Microsoft 标识平台注册 Web API 并通过添加范围将其公开到客户端应用。 通过注册 Web API 并通过范围将其公开，分配所有者和应用角色，你可以向可访问 API 的已授权用户和客户端应用提供对其资源的基于权限的访问权限。

先决条件

注册 Web API

访问 API 需要配置访问作用域和访问角色。 如果想要将资源应用程序 Web API 公开至客户端应用程序，请为 API 配置访问作用域和访问角色。 如果想要让客户端应用程序访问 Web API，请配置权限以访问应用注册中的 API。

若要提供对 Web API 中资源的范围访问权限，首先需要向 Microsoft 标识平台注册该 API。

执行以下文章的“注册应用程序”部分中的步骤：快速入门：将应用注册到 Microsoft 标识平台。

跳过“重定向 URI (可选)”部分。 无需为 Web API 配置重定向 URI，因为没有用户以交互方式进行登录。

分配应用程序所有者

  1. 在应用注册中的“管理”下，选择“所有者”，然后选择“添加所有者”。
  2. 在新窗口中，找到并选择要分配给应用程序的所有者。 所选所有者将显示在右侧面板中。 完成后，通过“选择”进行确认。 应用所有者现在将显示在所有者列表中。

注意

确保要对其添加权限的 API 应用程序和应用程序都具有所有者，否则在请求 API 权限时不会列出 API。

分配应用角色

  1. 在应用注册的“管理”下，选择“应用角色”和“创建应用角色”。

  2. 接下来，在“创建应用角色”窗格中指定应用角色的属性。 对于本演练，你可以使用示例值或指定自己的值。

    字段 说明 示例
    显示名称 应用角色的名称 员工记录
    允许的成员类型 指定是否可以将应用角色分配给用户/组和/或应用程序 应用程序
    值 令牌的“角色”声明中显示的值 Employee.Records
    描述 应用角色的更详细说明。 应用程序有权访问员工记录

  3. 选中复选框以启用应用角色。

注册 Web API、分配应用角色和所有者后，可以将范围添加到 API 的代码，以便它向使用者提供精细权限。

添加作用域

提示

本文中的步骤可能因开始使用的门户而略有不同。

客户端应用程序中的代码通过将访问令牌及其请求传递到受保护的资源 (Web API) 来请求执行由 Web API 定义的操作的权限。 然后，仅当 Web API 接收的访问令牌包含操作所需的范围时，Web API 才会执行请求的操作。

首先，请按照以下步骤创建一个名为 Employees.Read.All 的示例范围：

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

  2. 如果有权访问多个租户，请使用顶部菜单中的“设置”图标 ，从“目录 + 订阅”菜单切换到包含应用注册的租户。

  3. 浏览到“标识>应用程序>应用注册，然后选择 API 的应用注册。

  4. 选择“公开 API”

  5. 如果尚未配置应用程序 ID URI，请选择“应用程序 ID URI”旁的“添加”。

    你可以使用默认值api://<application-client-id>或者另一个“受支持的应用 ID URI 模式”。 应用 ID URI 充当你将在 API 代码中引用的范围的前缀，它必须是全局唯一的。

  6. 选择“添加范围”：

    An app registration's Expose an API pane in the Azure portal

  7. 接下来，在“添加范围”窗格中指定范围的属性。 对于本演练，你可以使用示例值或指定自己的值。

    字段 说明 示例
    范围名称 范围的名称。 常用的范围命名约定为 resource.operation.constraint。 Employees.Read.All
    谁可以许可 此范围是由用户同意，还是由管理员同意。 若要获得更高特权，请选择“仅管理员”。 管理员和用户
    管理员许可显示名称 仅管理员可以看到的范围用途的简短说明。 Read-only access to Employee records
    管理员许可说明 仅管理员可以看到的范围所授予权限的更详细说明。 Allow the application to have read-only access to all Employee data.
    用户许可显示名称 范围用途的简短说明。 仅当你将“谁可以同意”设置为“管理员和用户”时才向用户显示 。 Read-only access to your Employee records
    用户许可说明 范围所授予权限的更详细说明。 仅当你将“谁可以同意”设置为“管理员和用户”时才向用户显示 。 Allow the application to have read-only access to your Employee data.

  8. 将“状态”设置为“启用”，然后选择“添加范围” 。

  9. （可选）若要取消向应用用户提示同意你定义的范围，可以预授权客户端应用程序访问 Web API。 请仅预授权所信任的客户端应用程序，因为用户不会有机会拒绝同意。

    1. 在“授权客户端应用程序”下，选择“添加客户端应用程序”
    2. 输入要预授权的客户端应用程序的“应用程序(客户端) ID”。 例如，以前注册的 Web 应用程序的 ID。
    3. 在“授权的范围”下，选择要取消显示许可提示的范围，然后选择“添加应用程序”。

    如果遵循此可选步骤，则客户端应用现在是预授权的客户端应用 (PCA)，系统在用户登录时不会提示用户同意。

接下来，添加另一个名为 Employees.Write.All 的示例范围，只有管理员才能同意该范围。 需要管理员同意的范围通常用于提供对更高特权的操作的访问权限，并且通常由作为后端服务运行的客户端应用程序或不以交互方式登录用户的后台程序使用。

若要添加 Employees.Write.All 示例范围，请按照 添加范围 部分中的步骤进行操作，并在“添加范围”窗格中指定以下值：

字段 示例值
范围名称 Employees.Write.All
谁可以许可 仅管理员
管理员许可显示名称 Write access to Employee records
管理员许可说明 Allow the application to have write access to all Employee data.
用户许可显示名称 无（留空）
用户许可说明 无（留空）

将“状态”设置为“启用”，然后选择“添加范围” 。

验证公开的范围

如果你已成功添加先前部分中所介绍的两个示例范围，它们将显示在 Web API 的应用注册的“公开 API”窗格中，如以下图片所示：

Screenshot of the Expose an API pane showing two exposed scopes.

如图所示，范围的完整字符串由 Web API 的“应用程序 ID URI”与范围的“范围名称”串联而成 。

例如，如果 Web API 的应用程序 ID URI 为 https://contoso.com/api，范围名称为 Employees.Read.All，则完整范围为：

https://contoso.com/api/Employees.Read.All

使用公开的范围

在本系列的下一篇文章中，你将按照本文中的步骤配置客户端应用的注册，其中包含对 Web API 的访问权限和你所定义的范围。

向客户端应用注册授予访问 Web API 的权限后，标识平台可以向客户端颁发 OAuth 2.0 访问令牌。 当客户端调用 Web API 时，它会提供一个访问令牌，令牌的范围 (scp) 声明设置为你在客户端的应用注册中所指定的权限。

以后可以根据需要公开其他范围。 请考虑 Web API 可以公开与多个操作关联的多个范围。 在运行时，资源可以通过评估其收到的 OAuth 2.0 访问令牌中的范围 (scp) 声明，来控制对 Web API 的访问。

后续步骤

现在，你已通过配置 Web API 范围对其进行了公开，请使用访问范围的权限来配置客户端应用的注册。

配置应用注册以访问 Web API