快速入门:配置客户端应用程序以访问 Web API

在本快速入门中,针对向 Microsoft 标识平台注册的客户端应用,你将提供对你自己的 Web API 的范围内基于权限的访问。 你还将向客户端应用提供访问 Microsoft Graph 的权限。

通过在客户端应用的注册中指定 Web API 的范围,客户端应用可从 Microsoft 标识平台获取包含这些范围的访问令牌。 然后在其代码内,Web API 可基于访问令牌中的范围提供对其资源的基于权限的访问。

先决条件

添加用于访问 Web API 的权限

提示

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

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

若要授予客户端应用程序访问自己的 Web API 的权限,需要有两个应用注册;

此图显示了两个应用注册的相互关联方式,其中客户端应用具有不同的权限类型,Web API 具有客户端应用程序可以访问的不同范围。 在本部分中,将向客户端应用的注册添加权限。

一个显示 Web API 的线形图,其中右侧有公开的范围,左侧有客户端应用程序,且这些范围选为权限

注册客户端应用和 Web API,并通过创建范围公开 API 后,可按照以下步骤来配置客户端对 API 的权限:

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

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

  3. 浏览到“标识”>“应用程序”>“应用注册”,然后选择客户端应用程序(而不是 Web API)。

  4. 选择“API 权限”,再选择“添加权限”,然后在边栏中选择“我的 API”

  5. 选择作为先决条件一部分注册的 Web API,然后选择“委派的权限”

    • 委托的权限适用于这样的客户端应用,它们以登录用户身份访问 Web API,且其访问权限应仅限于在下一步中选择的权限。 在本例中,请选择“委托的权限”。

    • 应用程序权限适用于服务类型或守护程序类型的应用程序,这些应用需要以自身身份访问 Web API,而无需用户交互来进行登录或同意。 除非已为 Web API 定义了应用程序角色,否则禁用此选项。

  6. 在“选择权限”下,展开为 Web API 定义其范围的资源,并选择客户端应用代表已登录用户应具有的权限。

    • 如果使用了上一个快速入门中指定的示例范围名称,则应会看到 Employees.Read.All 和 Employees.Write.All
  7. 选择在完成先决条件时创建的权限,例如 Employees.Read.All

  8. 选择“添加权限”以完成此过程。

将权限添加到 API 后,应在“配置的权限”下看到所选权限。 下图显示了示例 Employees.Read.All 委托的权限已添加到客户端应用的注册。

Azure 门户中的“配置的权限”窗格,其中显示了新添加的权限

你可能还会注意到 Microsoft Graph API 的 User.Read 权限。 在 Azure 门户中注册应用时,会自动添加此权限。

添加用于访问 Microsoft Graph 的权限

除了代表已登录用户访问你自己的 Web API 外,应用程序可能还需要访问或修改 Microsoft Graph 中存储的用户的(或其他)数据。 或者,你可能有需要自行访问 Microsoft Graph 的服务或守护程序应用,无需任何用户交互即可执行操作。

Microsoft Graph 的委托权限

配置 Microsoft Graph 的委派权限,使客户端应用程序可代表已登录用户执行操作,例如读取其电子邮件或修改其个人资料。 默认情况下,在客户端应用的用户登录时,会询问他们是否同意你为其配置的委派权限。

  1. 在客户端应用程序的“概述”页面,选择“API 权限”>“添加权限”>“Microsoft Graph”

  2. 选择“委托的权限”。 Microsoft Graph 公开了许多权限,最常用的权限显示在列表顶部。

  3. 在“选择权限”下,选择以下权限:

    权限 说明
    email 查看用户的电子邮件地址
    offline_access 维护对已授予访问权限的数据的访问权限
    openid 登录用户
    profile 查看用户的基本配置文件
  4. 选择“添加权限”以完成此过程。

无论何时配置权限,都将在登录时请求应用用户同意允许你的应用代表他们访问资源 API。

作为管理员,你还可代表所有用户授予同意,以便不提示这些用户执行此操作。 稍后会在本文的详细介绍 API 权限和管理员同意部分讨论管理员同意。

Microsoft Graph 的应用程序权限

为需要进行身份验证的应用程序配置应用程序权限,而无需用户交互或同意。 应用程序权限通常由以“无外设”方式访问 API 的后台服务或守护程序应用,以及访问另一个(下游)API 的 Web API 使用。

在以下步骤中,例如将授予 Microsoft Graph 的 Files.Read.All 权限。

  1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心
  2. 如果有权访问多个租户,请使用顶部菜单中的“设置”图标 ,从“目录 + 订阅”菜单切换到包含应用注册的租户。
  3. 浏览到“标识”>“应用程序”>“应用注册”,然后选择客户端应用程序。
  4. 选择“API 权限”>“添加权限”>“Microsoft Graph”>“应用程序权限” 。
  5. Microsoft Graph 公开的所有权限都显示在“选择权限”下。
  6. 选择要授予应用程序的一项或多项权限。 例如,你可能有一个守护程序应用,它用于扫描组织中的文件,并对特定文件类型或名称发出警报。 在“选择权限”下展开“文件”,然后选择 Files.Read.All 权限
  7. 选择“添加权限”。
  8. 某些权限(例如 Microsoft Graph 的 Files.Read.All 权限)需要管理员同意。 可通过选择“授予管理员同意”按钮来授予此类同意,这一点稍后将在管理员同意按钮部分中进行讨论。

配置客户端凭据

使用应用程序权限的应用通过使用自己的凭据自行进行身份验证,无需任何用户交互。 你必须先配置该客户端应用的凭据,然后应用程序(或 API)才能使用应用程序权限访问 Microsoft Graph、你自己的 Web API 或其他 API。

若要详细了解如何配置应用的凭据,请参阅添加凭据部分 - 快速入门:将应用程序注册到 Microsoft 标识平台

应用注册的“API 权限”窗格包含配置的权限表和管理员同意按钮,如以下部分所述

已配置权限

“API 权限”窗格上的“配置的权限”表显示了应用程序在执行基本操作时需要的权限列表 - 必需的资源访问 (RRA) 列表 。 用户或其管理员需要在使用你的应用前同意这些权限。 稍后可在运行时(使用动态同意)请求其他可选权限。

这是用户同意你的应用所需的最小权限列表。 可能还有更多权限,但总是需要这些权限。 为了安全起见,并让用户和管理员更舒适地使用你的应用,请勿询问不需要的内容。

可按照上面概述的步骤添加或删除此表中显示的权限。 作为管理员,你可授予管理员同意表中出现的一整套 API 权限并撤销对单个权限的同意。

通过“为 {你的租户} 授予其他权限”按钮,管理员可向为应用程序配置的权限授予管理员同意。 选择该按钮后,会显示一个对话框,请求确认同意操作。

Azure 门户中的“配置的权限”窗格中突出显示了“授予管理员同意”按钮

授予同意后,要求管理员同意的权限显示为“已获得权限”:

在 Azure 门户中“配置权限”表,其中显示了已为 Files.Read.All 权限授予管理员同意

如果你不是管理员,或者没有为应用程序配置任何权限,则将禁用“授予管理员同意”按钮。 如果你获得了权限但尚未配置它们,则“管理员同意”按钮会提示你处理这些权限。 可将它们添加到已配置的权限,或者将其删除。

删除应用程序权限

请勿为应用程序提供过多的权限,而只需提供必需的权限。 若要撤销管理员对应用程序中权限的同意,请执行以下操作:

  1. 导航到应用程序并选择“API 权限”。
  2. 在“配置的权限”下,选择要删除的权限旁边的三个点,然后选择“删除权限”。
  3. 在显示的弹出窗口中,选择“是,删除”以撤销管理员对该权限的同意。

转到本系列的下一个快速入门,了解如何配置可以访问应用程序的帐户类型。 例如,你可能希望将访问权限仅限于组织(单租户)中的用户,或者允许其他 Microsoft Entra 租户(多租户)中的用户和拥有个人 Microsoft 帐户 (MSA) 的用户。