快速入门:配置应用程序来公开 Web APIQuickstart: Configure an application to expose web APIs

可以开发一个 Web API,并通过公开权限/范围角色,使其可供客户端应用程序使用。You can develop a web API and make it available to client applications by exposing permissions/scopes and roles. 可以像提供其他 Microsoft Web API(包括图形 API 和 Office 365 API)一样提供正确配置的 Web API。A correctly configured web API is made available just like the other Microsoft web APIs, including the Graph API and the Office 365 APIs.

本快速入门介绍如何将应用程序配置为公开新的范围,使其可供客户端应用程序使用。In this quickstart, you'll learn how to configure an application to expose a new scope to make it available to client applications.

先决条件Prerequisites

若要开始,请确保满足下列先决条件:To get started, make sure you complete these prerequisites:

登录到 Azure 门户,并选择应用Sign in to the Azure portal and select the app

在配置应用之前,请执行以下步骤:Before you can configure the app, follow these steps:

  1. 使用工作或学校帐户登录到 Azure 门户Sign in to the Azure portal using a work or school account.
  2. 如果你的帐户有权访问多个租户,请在右上角选择该帐户,并将门户会话设置为所需的 Azure AD 租户。If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant.
  3. 在左侧导航窗格中,选择“Azure Active Directory”服务 ,然后选择“应用注册”。 In the left-hand navigation pane, select the Azure Active Directory service and then select App registrations.
  4. 找到并选择要配置的应用程序。Find and select the application you want to configure. 选择应用以后,会看到应用程序的“概览”页或主注册页。 Once you've selected the app, you'll see the application's Overview or main registration page.
  5. 选择要使用哪个方法、UI 或应用程序清单来公开新的范围:Choose which method you want to use, UI or application manifest, to expose a new scope:

通过 UI 公开新的范围Expose a new scope through the UI

演示如何使用 UI 公开 APIShows how to expose an API using the UI

若要通过 UI 公开新的范围,请执行以下操作:To expose a new scope through the UI:

  1. 在应用的“概览”页中,选择“公开 API”部分。 From the app's Overview page, select the Expose an API section.

  2. 选择“添加范围”。 Select Add a scope.

  3. 如果尚未设置“应用程序 ID URI”,则会看到一个提示你输入它的提示。 If you have not set an Application ID URI, you will see a prompt to enter one. 输入应用程序 ID URI 或使用已提供的,然后选择“保存并继续”。 Enter your application ID URI or use the one provided and then select Save and continue.

  4. 出现“添加范围”页时,输入范围的信息: When the Add a scope page appears, enter your scope's information:

    字段Field 说明Description
    范围名称Scope name 为范围输入一个有意义的名称。Enter a meaningful name for your scope.

    例如,Employees.Read.AllFor example, Employees.Read.All.
    谁可以许可Who can consent 选择是让用户许可此范围,还是让管理员许可。Select whether this scope can be consented to by users, or if admin consent is required. 若要获得更高特权,请选择“仅管理员”。 Select Admins only for higher-privileged permissions.
    管理员许可显示名称Admin consent display name 为范围输入管理员会看到的有意义说明。Enter a meaningful description for your scope, which admins will see.

    例如: Read-only access to Employee recordsFor example, Read-only access to Employee records
    管理员许可说明Admin consent description 为范围输入管理员会看到的有意义说明。Enter a meaningful description for your scope, which admins will see.

    例如: Allow the application to have read-only access to all Employee data.For example, Allow the application to have read-only access to all Employee data.

    如果用户可以许可你的范围,另请添加以下字段的值:If users can consent to your scope, also add values for the following fields:

    字段Field 说明Description
    用户许可显示名称User consent display name 为范围输入一个用户会看到的有意义名称。Enter a meaningful name for your scope, which users will see.

    例如: Read-only access to your Employee recordsFor example, Read-only access to your Employee records
    用户许可说明User consent description 为范围输入用户会看到的有意义说明。Enter a meaningful description for your scope, which users will see.

    例如: Allow the application to have read-only access to your Employee data.For example, Allow the application to have read-only access to your Employee data.
  5. 完成后,设置“状态”并选择“添加范围”。 Set the State and select Add scope when you're done.

  6. 按步骤验证 Web API 是否已公开给其他应用程序Follow the steps to verify that the web API is exposed to other applications.

通过应用程序清单公开新的范围或角色Expose a new scope or role through the application manifest

使用清单中的 oauth2Permissions 集合公开新的范围Expose a new scope using the oauth2Permissions collection in the manifest

若要通过应用程序清单公开新的范围,请执行以下操作:To expose a new scope through the application manifest:

  1. 在应用的“概览”页中,选择“清单”部分。 From the app's Overview page, select the Manifest section. 此时会打开一个基于 Web 的清单编辑器,可在其中编辑门户中的清单。A web-based manifest editor opens, allowing you to Edit the manifest within the portal. (可选)可以选择“下载”并在本地编辑清单,然后使用“上传”将清单重新应用到应用程序。 Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application.

    以下示例介绍通过将以下 JSON 元素添加到 oauth2Permissions 集合,在资源/API 中公开一个名为 Employees.Read.All 的新范围。The following example shows how to expose a new scope called Employees.Read.All in the resource/API by adding the following JSON element to the oauth2Permissions collection.

    {
      "adminConsentDescription": "Allow the application to have read-only access to all Employee data.",
      "adminConsentDisplayName": "Read-only access to Employee records",
      "id": "2b351394-d7a7-4a84-841e-08a6a17e4cb8",
      "isEnabled": true,
      "type": "User",
      "userConsentDescription": "Allow the application to have read-only access to your Employee data.",
      "userConsentDisplayName": "Read-only access to your Employee records",
      "value": "Employees.Read.All"
    }
    

    备注

    必须通过编程方式或 GUID 生成工具(例如 guidgen)来生成 id 值。The id value must be generated programmatically or by using a GUID generation tool such as guidgen. id 表示 Web API 公开的范围的唯一标识符。The id represents a unique identifier for the scope as exposed by the web API. 为客户端配置访问 Web API 的适当权限后,Azure AD 将为它颁发 OAuth 2.0 访问令牌。Once a client is appropriately configured with permissions to access your web API, it is issued an OAuth 2.0 access token by Azure AD. 当客户端调用 Web API 时,会出示该访问令牌,其中的范围 (scp) 声明设置为客户端应用程序注册中请求的权限。When the client calls the web API, it presents the access token that has the scope (scp) claim set to the permissions requested in its application registration.

    以后可以根据需要公开其他范围。You can expose additional scopes later as necessary. 请考虑 Web API 可能要公开与各种不同功能关联的多个范围。Consider that your web API might expose multiple scopes associated with a variety of different functions. 在运行时,资源可以通过评估所收到的 OAuth 2.0 访问令牌中的范围 (scp) 声明,来控制对 Web API 的访问。Your resource can control access to the web API at runtime by evaluating the scope (scp) claim(s) in the received OAuth 2.0 access token.

  2. 完成后,单击“保存” 。When finished, click Save. 现在,Web API 已配置为可供目录中的其他应用程序使用。Now your web API is configured for use by other applications in your directory.

  3. 按步骤验证 Web API 是否已公开给其他应用程序Follow the steps to verify that the web API is exposed to other applications.

验证 Web API 是否已公开给其他应用程序Verify the web API is exposed to other applications

  1. 返回到 Azure AD 租户,选择“应用注册”,找到并选择要配置的客户端应用程序。 Go back to your Azure AD tenant, select App registrations, find and select the client application you want to configure.
  2. 重复将客户端应用程序配置为访问 Web API 中概述的步骤。Repeat the steps outlined in Configure a client application to access web APIs.
  3. 执行到选择 API 这一步时,请选择资源。When you get to the step to select an API, select your resource. 此时会看到可供客户端权限请求使用的新范围。You should see the new scope, available for client permission requests.

有关应用程序清单的更多信息More on the application manifest

应用程序清单充当了用于更新应用程序实体的机制,它定义了 Azure AD 应用程序的标识配置的所有属性。The application manifest serves as a mechanism for updating the application entity, which defines all attributes of an Azure AD application's identity configuration. 有关应用程序实体及其架构的详细信息,请参阅图形 API 应用程序实体文档For more information on the Application entity and its schema, see the Graph API Application entity documentation. 此文包含有关用于指定 API 权限的应用程序实体成员的完整参考信息,包括:The article contains complete reference information on the Application entity members used to specify permissions for your API, including:

有关应用程序清单概念的一般详细信息,请参阅了解 Azure Active Directory 应用程序清单For more information on application manifest concepts in general, see Understanding the Azure Active Directory application manifest.

后续步骤Next steps

了解下述其他相关的应用管理快速入门:Learn about these other related app management quickstarts for apps:

了解有关表示已注册应用程序和它们之间的关系的两个 Azure AD 对象的详细信息,请参阅应用程序对象和服务主体对象To learn more about the two Azure AD objects that represent a registered application and the relationship between them, see Application objects and service principal objects.

深入了解使用 Azure Active Directory 开发应用程序时应使用的品牌准则,请参阅应用程序的品牌准则To learn more about the branding guidelines you should use when developing applications with Azure Active Directory, see Branding guidelines for applications.