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

本快速入门将向 Microsoft 标识平台注册 Web API 并通过添加示例范围将其公开到客户端应用。In this quickstart, you register a web API with the Microsoft identity platform and expose it to client apps by adding an example scope. 通过注册 Web API 并通过范围将其公开,你可以向可访问 API 的已授权用户和客户端应用提供对其资源的基于权限的访问权限。By registering your web API and exposing it through scopes, you can provide permissions-based access to its resources to authorized users and client apps that access your API.

先决条件Prerequisites

注册 Web APIRegister the web API

若要提供对 Web API 中资源的范围访问权限,首先需要向 Microsoft 标识平台注册该 API。To provide scoped access to the resources in your web API, you first need to register the API with the Microsoft identity platform.

  1. 执行以下文章的“注册应用程序”部分中的步骤:快速入门:将应用注册到 Microsoft 标识平台Perform the steps in the Register an application section of Quickstart: Register an app with the Microsoft identity platform.
  2. 跳过“添加重定向 URI”和“配置平台设置”部分 。Skip the Add a redirect URI and Configure platform settings sections. 无需为 Web API 配置重定向 URI,因为没有用户以交互方式进行登录。You don't need to configure a redirect URI for a web API since no user is logged in interactively.
  3. 暂时跳过“添加凭据”部分。Skip the Add credentials section for now. 仅当你的 API 访问下游 API 时,它才需要其自己的凭据,这是本文未涵盖的方案。Only if your API accesses a downstream API would it need its own credentials, a scenario not covered in this article.

注册 Web API 后,便可以添加范围,API 的代码可使用这些范围向 API 的使用者提供具体权限。With your web API registered, you're ready to add the scopes that your API's code can use to provide granular permission to consumers of your API.

添加作用域Add a scope

客户端应用程序中的代码通过将访问令牌及其请求传递到受保护的资源 (Web API) 来请求执行由 Web API 定义的操作的权限。The code in a client application requests permission to perform operations defined by your web API by passing an access token along with its requests to the protected resource (the web API). 然后,仅当 Web API 接收的访问令牌包含操作所需的范围时,Web API 才会执行请求的操作。Your web API then performs the requested operation only if the access token it receives contains the scopes required for the operation.

首先,请按照以下步骤创建一个名为 Employees.Read.All 的示例范围:First, follow these steps to create an example scope named Employees.Read.All:

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

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

  3. 选择“Azure Active Directory” > “应用注册”,然后选择 API 的应用注册 。Select Azure Active Directory > App registrations, and then select your API's app registration.

  4. 依次选择“公开 API” > “添加范围” 。Select Expose an API > Add a scope.

    Azure 门户中应用注册的“公开 API”窗格

  5. 如果尚未配置应用程序 ID URI,系统会提示你设置一个。You're prompted to set an Application ID URI if you haven't yet configured one.

    应用 ID URI 充当你将在 API 代码中引用的范围的前缀,它必须是全局唯一的。The App ID URI acts as the prefix for the scopes you'll reference in your API's code, and it must be globally unique. 你可以使用提供的默认值(格式为 api://<application-client-id>)或指定更具可读性的 URI,例如 https://contoso.com/apiYou can use the default value provided, which is in the form api://<application-client-id>, or specify a more readable URI like https://contoso.com/api.

  6. 接下来,在“添加范围”窗格中指定范围的属性。Next, specify the scope's attributes in the Add a scope pane. 对于本演练,你可以使用示例值或指定自己的值。For this walk-through, you can use the example values or specify your own.

    字段Field 说明Description 示例Example
    范围名称Scope name 范围的名称。The name of your scope. 常用的范围命名约定为 resource.operation.constraintA common scope naming convention is resource.operation.constraint. Employees.Read.All
    谁可以许可Who can consent 此范围是由用户同意,还是由管理员同意。Whether this scope can be consented to by users or if admin consent is required. 若要获得更高特权,请选择“仅管理员”。 Select Admins only for higher-privileged permissions. 管理员和用户Admins and users
    管理员许可显示名称Admin consent display name 仅管理员可以看到的范围用途的简短说明。A short description of the scope's purpose that only admins will see. Read-only access to Employee records
    管理员许可说明Admin consent description 仅管理员可以看到的范围所授予权限的更详细说明。A more detailed description of the permission granted by the scope that only admins will see. Allow the application to have read-only access to all Employee data.
    用户许可显示名称User consent display name 范围用途的简短说明。A short description of the scope's purpose. 仅当你将“谁可以同意”设置为“管理员和用户”时才向用户显示 。Shown to users only if you set Who can consent to Admins and users. Read-only access to your Employee records
    用户许可说明User consent description 范围所授予权限的更详细说明。A more detailed description of the permission granted by the scope. 仅当你将“谁可以同意”设置为“管理员和用户”时才向用户显示 。Shown to users only if you set Who can consent to Admins and users. Allow the application to have read-only access to your Employee data.
  7. 将“状态”设置为“启用”,然后选择“添加范围” 。Set the State to Enabled, and then select Add scope.

  8. (可选)若要取消向应用用户提示同意你定义的范围,可以预授权客户端应用程序访问 Web API。(Optional) To suppress prompting for consent by users of your app to the scopes you've defined, you can pre-authorize the client application to access your web API. 请仅预授权所信任的客户端应用程序,因为用户不会有机会拒绝同意。Pre-authorize only those client applications you trust since your users won't have the opportunity to decline consent.

    1. 在“授权客户端应用程序”下,选择“添加客户端应用程序”Under Authorized client applications, select Add a client application
    2. 输入要预授权的客户端应用程序的“应用程序(客户端) ID”。Enter the Application (client) ID of the client application you want to pre-authorize. 例如,以前注册的 Web 应用程序的 ID。For example, that of a web application you've previously registered.
    3. 在“授权的范围”下,选择要取消显示许可提示的范围,然后选择“添加应用程序”。Under Authorized scopes, select the scopes for which you want to suppress consent prompting, then select Add application.

    如果遵循此可选步骤,则客户端应用现在是预授权的客户端应用 (PCA),系统在用户登录时不会提示用户同意。If you followed this optional step, the client app is now a pre-authorized client app (PCA), and users won't be prompted for their consent when signing in to it.

接下来,添加另一个名为 Employees.Write.All 的示例范围,只有管理员才能同意该范围。Next, add another example scope named Employees.Write.All that only admins can consent to. 需要管理员同意的范围通常用于提供对更高特权的操作的访问权限,并且通常由作为后端服务运行的客户端应用程序或不以交互方式登录用户的后台程序使用。Scopes that require admin consent are typically used for providing access to higher-privileged operations, and often by client applications that run as backend services or daemons that don't sign in a user interactively.

若要添加 Employees.Write.All 示例范围,请按照 添加范围 部分中的步骤进行操作,并在“添加范围”窗格中指定以下值:To add the Employees.Write.All example scope, follow the steps in the Add a scope section and specify these values in the Add a scope pane:

字段Field 示例值Example value
范围名称Scope name Employees.Write.All
谁可以许可Who can consent 仅管理员Admins only
管理员许可显示名称Admin consent display name Write access to Employee records
管理员许可说明Admin consent description Allow the application to have write access to all Employee data.
用户许可显示名称User consent display name 无(留空)None (leave empty)
用户许可说明User consent description 无(留空)None (leave empty)

验证公开的范围Verify the exposed scopes

如果你已成功添加先前部分中所介绍的两个示例范围,则它们将显示在 Web API 的应用注册的“公开 API”窗格中,类似于以下内容:If you successfully added both example scopes described in the previous sections, they'll appear in the Expose an API pane of your web API's app registration, similar to this image:

Azure 门户中应用注册的“公开 API”窗格

如图所示,范围的完整字符串由 Web API 的“应用程序 ID URI”与范围的“范围名称”串联而成 。As shown in the image, a scope's full string is the concatenation of your web API's Application ID URI and the scope's Scope name.

例如,如果 Web API 的应用程序 ID URI 为 https://contoso.com/api,范围名称为 Employees.Read.All,则完整范围为:For example, if your web API's application ID URI is https://contoso.com/api and the scope name is Employees.Read.All, the full scope is:

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

使用公开的范围Using the exposed scopes

在本系列的下一篇文章中,你将按照本文中的步骤配置客户端应用的注册,其中包含对 Web API 的访问权限和你所定义的范围。In the next article in the series, you configure a client app's registration with access to your web API and the scopes you defined by following the steps this article.

向客户端应用注册授予访问 Web API 的权限后,Microsoft 标识平台可以向客户端颁发 OAuth 2.0 访问令牌。Once a client app registration is granted permission to access your web API, the client can be issued an OAuth 2.0 access token by the Microsoft identity platform. 当客户端调用 Web API 时,它会提供一个访问令牌,令牌的范围 (scp) 声明设置为你在客户端的应用注册中所指定的权限。When the client calls the web API, it presents an access token whose scope (scp) claim is set to the permissions you've specified in the client's app registration.

以后可以根据需要公开其他范围。You can expose additional scopes later as necessary. 请考虑 Web API 可以公开与多个操作关联的多个范围。Consider that your web API can expose multiple scopes associated with several operations. 在运行时,资源可以通过评估其收到的 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 OAuth 2.0 access token it receives.

后续步骤Next steps

现在,你已通过配置 Web API 范围对其进行了公开,请使用访问范围的权限来配置客户端应用的注册。Now that you've exposed your web API by configuring its scopes, configure your client app's registration with permission to access the scopes.