快速入门:配置客户端应用程序以访问 Web APIQuickstart: Configure a client application to access a web API

在本快速入门中,针对向 Microsoft 标识平台注册的客户端应用,你将提供对你自己的 Web API 的范围内基于权限的访问。In this quickstart, you provide a client app registered with the Microsoft identity platform with scoped, permissions-based access to your own web API. 你还将向客户端应用提供访问 Microsoft Graph 的权限。You also provide the client app access to Microsoft Graph.

通过在客户端应用的注册中指定 Web API 的范围,客户端应用可从 Microsoft 标识平台获取包含这些范围的访问令牌。By specifying a web API's scopes in your client app's registration, the client app can obtain an access token containing those scopes from the Microsoft identity platform. 然后在其代码内,Web API 可基于访问令牌中的范围提供对其资源的基于权限的访问。Within its code, the web API can then provide permission-based access to its resources based on the scopes found in the access token.

先决条件Prerequisites

添加用于访问 Web API 的权限Add permissions to access your web API

在第一个方案中,向客户端应用授予访问你自己的 Web API 的权限 - 这两者都应作为先决条件的一部分进行注册。In the first scenario, you grant a client app access to your own web API, both of which you should have registered as part of the prerequisites. 如果尚未注册客户端应用和 Web API,请完成两篇先决条件文章中的步骤。If you don't yet have both a client app and a web API registered, complete the steps in the two Prerequisites articles.

此图显示了两个应用注册如何相互关联。This diagram shows how the two app registrations relate to one another. 在本部分中,将向客户端应用的注册添加权限。In this section, you add permissions to the client app's registration.

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

注册客户端应用和 Web API,并通过创建范围公开 API 后,可按照以下步骤来配置客户端对 API 的权限:Once you've registered both your client app and web API and you've exposed the API by creating scopes, you can configure the client's permissions to the API by following these steps:

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 如果有权访问多个租户,请使用顶部菜单中的“目录 + 订阅”筛选器 ,以选择包含客户端应用的注册的租户。

  3. 选择“Azure Active Directory” > “应用注册”,然后选择客户端应用程序(而不是 Web API) 。Select Azure Active Directory > App registrations, and then select your client application (not your web API).

  4. 选择“API 权限” > “添加权限” > “我的 API”。 Select API permissions > Add a permission > My APIs.

  5. 选择作为先决条件一部分注册的 Web API。Select the web API you registered as part of the prerequisites.

    默认情况下,选择“委托的权限”。Delegated permissions is selected by default. 委托的权限适用于这样的客户端应用,它们以登录用户身份访问 Web API,且其访问权限应仅限于在下一步中选择的权限。Delegated permissions are appropriate for client apps that access a web API as the signed-in user, and whose access should be restricted to the permissions you select in the next step. 在本例中,请选择“委托的权限”。Leave Delegated permissions selected for this example.

    应用程序权限适用于服务类型或守护程序类型的应用程序,这些应用需要以自身身份访问 Web API,而无需用户交互来进行登录或同意。Application permissions are for service- or daemon-type applications that need to access a web API as themselves, without user interaction for sign-in or consent. 除非已为 Web API 定义了应用程序角色,否则禁用此选项。Unless you've defined application roles for your web API, this option is disabled.

  6. 在“选择权限”下,展开为 Web API 定义其范围的资源,并选择客户端应用代表已登录用户应具有的权限。Under Select permissions, expand the resource whose scopes you defined for your web API, and select the permissions the client app should have on behalf of the signed-in user.

    如果使用了上一个快速入门中指定的示例范围名称,则应会看到 Employees.Read.All 和 Employees.Write.All 。If you used the example scope names specified in the previous quickstart, you should see Employees.Read.All and Employees.Write.All. 完成先决条件时,请选择 Employees.Read.All 或可能已创建的其他权限。Select Employees.Read.All or another permission you might have created when completing the prerequisites.

  7. 选择“添加权限”以完成此过程。Select Add permissions to complete the process.

将权限添加到 API 后,应在“配置的权限”下看到所选权限。After adding permissions to your API, you should see the selected permissions under Configured permissions. 下图显示了示例 Employees.Read.All 委托的权限已添加到客户端应用的注册。The following image shows the example Employees.Read.All delegated permission added to the client app's registration.

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

你可能还会注意到 Microsoft Graph API 的 User.Read 权限。You might also notice the User.Read permission for the Microsoft Graph API. 在 Azure 门户中注册应用时,会自动添加此权限。This permission is added automatically when you register an app in the Azure portal.

添加用于访问 Microsoft Graph 的权限Add permissions to access Microsoft Graph

除了代表已登录用户访问你自己的 Web API 外,应用程序可能还需要访问或修改 Microsoft Graph 中存储的用户的(或其他)数据。In addition to accessing your own web API on behalf of the signed-in user, your application might also need to access or modify the user's (or other) data stored in Microsoft Graph. 或者,你可能有需要自行访问 Microsoft Graph 的服务或守护程序应用,无需任何用户交互即可执行操作。Or you might have service or daemon app that needs to access Microsoft Graph as itself, performing operations without any user interaction.

Microsoft Graph 的委托权限Delegated permission to Microsoft Graph

配置 Microsoft Graph 的委派权限,使客户端应用程序可代表已登录用户执行操作,例如读取其电子邮件或修改其个人资料。Configure delegated permission to Microsoft Graph to enable your client application to perform operations on behalf of the logged-in user, for example reading their email or modifying their profile. 默认情况下,在客户端应用的用户登录时,会询问他们是否同意你为其配置的委派权限。By default, users of your client app are asked when they sign in to consent to the delegated permissions you've configured for it.

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 如果有权访问多个租户,请使用顶部菜单中的“目录 + 订阅”筛选器 ,以选择包含客户端应用的注册的租户。

  3. 选择“Azure Active Directory” > “应用注册”,然后选择客户端应用程序 。Select Azure Active Directory > App registrations, and then select your client application.

  4. 选择“API 权限” > “添加权限” > “Microsoft Graph” Select API permissions > Add a permission > Microsoft Graph

  5. 选择“委托的权限”。Select Delegated permissions. Microsoft Graph 公开了许多权限,最常用的权限显示在列表顶部。Microsoft Graph exposes many permissions, with the most commonly used shown at the top of the list.

  6. 在“选择权限”下,选择以下权限:Under Select permissions, select the following permissions:

    权限Permission 说明Description
    email 查看用户的电子邮件地址View users' email address
    offline_access 维护对已授予访问权限的数据的访问权限Maintain access to data you have given it access to
    openid 登录用户Sign users in
    profile 查看用户的基本配置文件View users' basic profile
  7. 选择“添加权限”以完成此过程。Select Add permissions to complete the process.

无论何时配置权限,都将在登录时请求应用用户同意允许你的应用代表他们访问资源 API。Whenever you configure permissions, users of your app are asked at sign-in for their consent to allow your app to access the resource API on their behalf.

作为管理员,你还可代表所有用户授予同意,以便不提示这些用户执行此操作。As an admin, you can also grant consent on behalf of all users so they're not prompted to do so. 稍后会在本文的详细介绍 API 权限和管理员同意部分讨论管理员同意。Admin consent is discussed later in the More on API permissions and admin consent section of this article.

Microsoft Graph 的应用程序权限Application permission to Microsoft Graph

为需要进行身份验证的应用程序配置应用程序权限,而无需用户交互或同意。Configure application permissions for an application that needs to authenticate as itself without user interaction or consent. 应用程序权限通常由以“无外设”方式访问 API 的后台服务或守护程序应用,以及访问另一个(下游)API 的 Web API 使用。Application permissions are typically used by background services or daemon apps that access an API in a "headless" manner, and by web APIs that access another (downstream) API.

在以下步骤中,例如将授予 Microsoft Graph 的 Files.Read.All 权限。In the following steps, you grant permission to Microsoft Graph's Files.Read.All permission as an example.

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 如果有权访问多个租户,请使用顶部菜单中的“目录 + 订阅”筛选器 ,以选择包含客户端应用的注册的租户。

  3. 选择“Azure Active Directory” > “应用注册”,然后选择客户端应用程序 。Select Azure Active Directory > App registrations, and then select your client application.

  4. 选择“API 权限” > “添加权限” > “Microsoft Graph” > “应用程序权限” 。Select API permissions > Add a permission > Microsoft Graph > Application permissions.

  5. Microsoft Graph 公开的所有权限都显示在“选择权限”下。All permissions exposed by Microsoft Graph are shown under Select permissions.

  6. 选择要授予应用程序的一项或多项权限。Select the permission or permissions you want to grant your application. 例如,你可能有一个守护程序应用,它用于扫描组织中的文件,并对特定文件类型或名称发出警报。As an example, you might have a daemon app that scans files in your organization, alerting on a specific file type or name.

    在“选择权限”下展开“文件”,然后选择“Files.Read.All”权限 。Under Select permissions, expand Files, and then select the Files.Read.All permission.

  7. 选择“添加权限”。Select Add permissions.

某些权限(例如 Microsoft Graph 的 Files.Read.All 权限)需要管理员同意。Some permissions, like Microsoft Graph's Files.Read.All permission, require admin consent. 可通过选择“授予管理员同意”按钮来授予此类同意,这一点稍后将在管理员同意按钮部分中进行讨论。You grant admin consent by selecting the Grant admin consent button, discussed later in the Admin consent button section.

配置客户端凭据Configure client credentials

使用应用程序权限的应用通过使用自己的凭据自行进行身份验证,无需任何用户交互。Apps that use application permissions authenticate as themselves by using their own credentials, without requiring any user interaction. 在应用程序(或 API)可通过使用应用程序权限访问 Microsoft Graph、你自己的 Web API 或其他任何 API 之前,需要配置该客户端应用的凭据。Before your application (or API) can access Microsoft Graph, your own web API, or any another API by using application permissions, you need to configure that client app's credentials.

若要详细了解如何配置应用的凭据,请参阅添加凭据部分 - 快速入门:将应用程序注册到 Microsoft 标识平台For more information about configuring an app's credentials, see the Add credentials section of Quickstart: Register an application with the Microsoft identity platform.

应用注册的“API 权限”窗格包含配置的权限表,还可能包含授予的其他权限表。The API permissions pane of an app registration contains a Configured permissions table, and might also contain an Other permissions granted table. 以下各部分介绍了这两个表和管理员同意按钮Both tables and the Admin consent button are described in the following sections.

已配置权限Configured permissions

“API 权限”窗格上的“配置的权限”表显示了应用程序在执行基本操作时需要的权限列表 - 必需的资源访问 (RRA) 列表 。The Configured permissions table on the API permissions pane shows the list of permissions that your application requires for basic operation - the required resource access (RRA) list. 用户或其管理员需要在使用你的应用前同意这些权限。Users, or their admins, will need to consent to these permissions before using your app. 稍后可在运行时(使用动态同意)请求其他可选权限。Other, optional permissions can be requested later at runtime (using dynamic consent).

这是用户同意你的应用所需的最小权限列表。This is the minimum list of permissions people will have to consent to for your app. 可能还有更多权限,但总是需要这些权限。There could be more, but these will always be required. 为了安全起见,并让用户和管理员更舒适地使用你的应用,请勿询问不需要的内容。For security and to help users and admins feel more comfortable using your app, never ask for anything you don’t need.

可按照上面概述的步骤或从授予的其他权限中(在下一部分中介绍)添加或删除此表中显示的权限。You can add or remove the permissions that appear in this table by using the steps outlined above or from Other permissions granted (described in the next section). 作为管理员,你可授予管理员同意表中出现的一整套 API 权限并撤销对单个权限的同意。As an admin, you can grant admin consent for the full set of an API's permissions that appear in the table, and revoke consent for individual permissions.

授予的其他权限Other permissions granted

你可能还会在“API 权限”窗格上看到标题是“为 {你的租户} 授予的其他权限”的表 。You might also see a table entitled Other permissions granted for {your tenant} on the API permissions pane. 在“为 {你的租户} 授予的其他权限”表中,显示了为租户授予的、未在应用程序对象中显式配置的权限。The Other permissions granted for {your tenant} table shows permissions granted for the tenant that haven't been explicitly configured on the application object. 这些权限是动态请求且获得同意的。These permissions were dynamically requested and consented to. 仅当至少应用了其中一个权限时,才会显示此部分。This section appears only if there is at least one permission that applies.

可将此表中显示的一整套 API 权限或单个权限添加到“已配置权限”表。You can add the full set of an API's permissions or individual permissions appearing this table to the Configured permissions table. 作为管理员,你可撤销此部分中对 API 或单个权限的管理员同意。As an admin, you can revoke admin consent for APIs or individual permissions in this section.

通过“为 {你的租户} 授予其他权限”按钮,管理员可向为应用程序配置的权限授予管理员同意。The Grant admin consent for {your tenant} button allows an admin to grant admin consent to the permissions configured for the application. 选择该按钮后,会显示一个对话框,请求确认同意操作。When you select the button, a dialog is shown requesting that you confirm the consent action.

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

授予同意后,要求管理员同意的权限显示为“已获得权限”:After granting consent, the permissions that required admin consent are shown as having consent granted:

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

如果你不是管理员,或者没有为应用程序配置任何权限,则将禁用“授予管理员同意”按钮。The Grant admin consent button is disabled if you aren't an admin or if no permissions have been configured for the application. 如果你获得了权限但尚未配置它们,则“管理员同意”按钮会提示你处理这些权限。If you have permissions that have been granted but not yet configured, the admin consent button prompts you to handle these permissions. 可将它们添加到已配置的权限,或者将其删除。You can add them to configured permissions or remove them.

后续步骤Next steps

转到本系列的下一个快速入门,了解如何配置可以访问应用程序的帐户类型。Advance to the next quickstart in the series to learn how to configure which account types can access your application. 例如,你可能希望将访问权限仅限于你的组织(单租户)中的用户,或者允许其他 Azure AD 租户(多租户)中的用户。For example, you might want to limit access only to those users in your organization (single-tenant) or allow users in other Azure AD tenants (multi-tenant).