受保护的 Web API:应用注册Protected web API: App registration

本文介绍适用于受保护 Web API 的应用注册详细信息。This article explains the specifics of app registration for a protected web API.

有关注册应用程序的常用步骤,请参阅快速入门:将应用程序注册到 Microsoft 标识平台For the common steps to register an app, see Quickstart: Register an application with the Microsoft identity platform.

接受的令牌版本Accepted token version

Microsoft 标识平台终结点可以发出 v1.0 令牌和 v2.0 令牌。The Microsoft identity platform endpoint can issue v1.0 tokens and v2.0 tokens. 有关这些令牌的详细信息,请参阅访问令牌For more information about these tokens, see Access tokens.

创建应用程序后,可以按以下步骤确定或更改接受的令牌版本:After you create the application, you can determine or change the accepted token version by following these steps:

  1. 在 Azure 门户中选择你的应用,然后选择“清单”。In the Azure portal, select your app and then select Manifest.
  2. 在清单中找到 accessTokenAcceptedVersion 属性。Find the property accessTokenAcceptedVersion in the manifest. 此属性的默认值为 2。The property's default value is 2.
  3. 该值向 Azure Active Directory (Azure AD) 指定 Web API 接受哪个令牌版本。The value specifies to Azure Active Directory (Azure AD) which token version the web API accepts.
    • 如果值为 2,则 Web API 接受 v2.0 令牌。If the value is 2, the web API accepts v2.0 tokens.
    • 如果值为 null,则 Web API 接受 v1.0 令牌。If the value is null, the web API accepts v1.0 tokens.
  4. 如果更改了令牌版本,请选择“保存”。If you changed the token version, select Save.

备注

Web API 会指定它所接受的令牌版本。The web API specifies which token version it accepts. 当客户端从 Microsoft 标识平台 (v2.0) 终结点请求 Web API 的令牌时,所获取的令牌会指示 Web API 接受哪个令牌版本。When a client requests a token for your web API from the Microsoft identity platform (v2.0) endpoint, the client gets a token that indicates which token version the web API accepts.

无重定向 URINo redirect URI

Web API 不需注册重定向 URI,因为没有任何用户以交互方式登录。Web APIs don't need to register a redirect URI because no user is interactively signed in.

公开的 APIExposed API

特定于 Web API 的其他设置是公开的 API 和公开的范围。Other settings specific to web APIs are the exposed API and the exposed scopes.

应用程序 ID URI 和范围Application ID URI and scopes

范围通常采用 resourceURI/scopeName 格式。Scopes usually have the form resourceURI/scopeName. 对于 Microsoft Graph,范围具有快捷方式。For Microsoft Graph, the scopes have shortcuts. 例如,User.Readhttps://microsoftgraph.chinacloudapi.cn/user.read 的快捷方式。For example, User.Read is a shortcut for https://microsoftgraph.chinacloudapi.cn/user.read.

在应用注册过程中,需定义以下参数:During app registration, you need to define these parameters:

  • 资源 URIThe resource URI
  • 一个或多个范围One or more scopes
  • 一个或多个应用角色One or more app roles

默认情况下,门户建议使用资源 URI api://{clientId}By default, the portal recommends that you use the resource URI api://{clientId}. 此 URI 是唯一的,但用户无法识别它。This URI is unique but not human readable. 如果更改 URI,请确保新值是唯一的。If you change the URI, make sure the new value is unique.

对于客户端应用程序,范围将显示为委托的权限,应用角色将显示为 Web API 的应用程序权限。 To client applications, scopes show up as delegated permissions and app roles show up as application permissions for your web API.

范围还会出现在向应用用户显示的许可窗口中。Scopes also appear on the consent window that's presented to users of your app. 因此,需要提供用于描述范围的相应字符串:So you need to provide the corresponding strings that describe the scope:

  • 用户看到的内容。As seen by a user.
  • 可授予管理员许可的租户管理员看到的内容。As seen by a tenant admin, who can grant admin consent.

公开委托的权限(范围)Exposing delegated permissions (scopes)

  1. 在应用程序注册中选择“公开 API”。Select Expose an API in the application registration.
  2. 选择“添加范围”。Select Add a scope.
  3. 出现提示时,请选择“保存并继续”,接受建议的应用程序 ID URI (api://{clientId})。If prompted, accept the proposed application ID URI (api://{clientId}) by selecting Save and Continue.
  4. 指定以下值:Specify these values:
    • 选择“范围名称”并输入 access_as_userSelect Scope name and enter access_as_user.
    • 选择“谁能许可”,并确保选择“管理员和用户”。 Select Who can consent and make sure Admins and users is selected.
    • 选择“管理员许可显示名称”,并输入“以用户身份访问 TodoListService”。 Select Admin consent display name and enter Access TodoListService as a user.
    • 选择“管理员同意说明”,并输入“以用户身份访问 TodoListService Web API”。 Select Admin consent description and enter Accesses the TodoListService web API as a user.
    • 选择“用户许可显示名称”,并输入“以用户身份访问 TodoListService”。 Select User consent display name and enter Access TodoListService as a user.
    • 选择“用户同意说明”,并输入“以用户身份访问 TodoListService Web API”。 Select User consent description and enter Accesses the TodoListService web API as a user.
    • 将“状态”值保留设置为“已启用”。 Keep the State value set to Enabled.
  5. 选择“添加作用域”。Select Add scope.

如果 Web API 由守护程序应用调用If your web API is called by a daemon app

本部分介绍如何注册受保护的 Web API,使守护程序应用可以安全地调用它。In this section, you learn how to register your protected web API so that daemon apps can securely call it.

  • 由于守护程序应用不与用户交互,因此请仅声明并公开应用程序权限。You declare and expose only application permissions because daemon apps don't interact with users. 委托的权限没有作用。Delegated permissions wouldn't make sense.
  • 租户管理员可以要求 Azure AD 仅将 Web API 令牌颁发给已注册的、可访问某个 API 的应用程序权限的应用程序。Tenant admins can require Azure AD to issue web API tokens only to applications that have registered to access one of the API's application permissions.

公开应用程序权限(应用角色)Exposing application permissions (app roles)

若要公开应用程序权限,需要编辑清单。To expose application permissions, you need to edit the manifest.

  1. 在应用程序的应用程序注册中选择“清单”。In the application registration for your application, select Manifest.
  2. 若要编辑清单,请找到 appRoles 设置并添加应用程序角色。To edit the manifest, find the appRoles setting and add application roles. 以下示例 JSON 块中提供了角色定义。The role definitions are provided in the following sample JSON block.
  3. 仅将 allowedMemberTypes 保留设置为 "Application"Leave allowedMemberTypes set to "Application" only.
  4. 确保 id 是唯一的 GUID。Make sure id is a unique GUID.
  5. 确保 displayNamevalue 不包含空格。Make sure displayName and value don't contain spaces.
  6. 保存清单。Save the manifest.

以下示例演示了 appRoles 的内容,其中 id 的值可以是任何唯一的 GUID。The following sample shows the contents of appRoles, where the value of id can be any unique GUID.

"appRoles": [
    {
    "allowedMemberTypes": [ "Application" ],
    "description": "Accesses the TodoListService-Cert as an application.",
    "displayName": "access_as_application",
    "id": "ccf784a6-fd0c-45f2-9c08-2f9d162a0628",
    "isEnabled": true,
    "lang": null,
    "origin": "Application",
    "value": "access_as_application"
    }
],

确保 Azure AD 仅向允许的客户端颁发 Web API 的令牌Ensuring that Azure AD issues tokens for your web API to only allowed clients

Web API 将检查应用角色。The web API checks for the app role. 此角色是软件开发人员公开应用程序权限的方式。This role is a software developer's way to expose application permissions. 还可以将 Azure AD 配置为仅向租户管理员批准的、可访问 API 的应用颁发 API 令牌。You can also configure Azure AD to issue API tokens only to apps that the tenant admin approves for API access.

若要添加此增强的安全性:To add this increased security:

  1. 转到应用注册的应用“概述”页。Go to the app Overview page for your app registration.

  2. 在“本地目录中的托管应用程序”下,选择包含应用名称的链接。Under Managed application in local directory, select the link with the name of your app. 此选项的标题可能已截断。The label for this selection might be truncated. 例如,你可能会看到“...中的托管应用程序”。For example, you might see Managed application in ...

    备注

    选择此链接后,会转到“企业应用程序概述”页。When you select this link, you go to the Enterprise Application Overview page. 此页与创建应用程序的租户中该应用程序的服务主体相关联。This page is associated with the service principal for your application in the tenant where you created it. 可以使用浏览器中的“后退”按钮转到应用注册页。You can go to the app registration page by using the back button of your browser.

  3. 在“企业应用程序”页的“管理”部分选择“属性”页。 Select the Properties page in the Manage section of the Enterprise application pages.

  4. 如果希望 Azure AD 仅允许从特定的客户端访问你的 Web API,请将“需要用户分配?”设置为“是”。 If you want Azure AD to allow access to your web API from only certain clients, set User assignment required? to Yes.

    重要

    如果将“需要用户分配?”设置为“是”,当客户端请求 Web API 访问令牌时,Azure AD 会检查这些客户端的应用角色分配。 If you set User assignment required? to Yes, Azure AD checks the app role assignments of a client when it requests a web API access token. 如果客户端未分配到任何应用角色,Azure AD 将返回错误消息“invalid_client:AADSTS501051:应用程序 <application name> 未分配给 <web API> 的角色”。If the client isn't assigned to any app roles, Azure AD will return the error message "invalid_client: AADSTS501051: Application <application name> is not assigned to a role for the <web API>".

    如果将“需要用户分配?”设置为“否”,当客户端请求 Web API 的访问令牌时,Azure AD 不会检查应用角色分配。 If you keep User assignment required? set to No, Azure AD won’t check the app role assignments when a client requests an access token for your web API. 任何守护程序客户端(即,任何使用客户端凭据流的客户端)只需指定其受众,即可获取 API 的访问令牌。Any daemon client, meaning any client using the client credentials flow, can get an access token for the API just by specifying its audience. 任何应用程序都可以访问 API,而无需请求其权限。Any application can access the API without having to request permissions for it.

    但是,如上一部分中所述,Web API 始终可以验证应用程序是否具有租户管理员授权的适当角色。API 的验证方式是验证访问令牌是否包含角色声明,以及此声明的值是否正确。But as explained in the previous section, your web API can always verify that the application has the right role, which is authorized by the tenant admin. The API performs this verification by validating that the access token has a roles claim and that the value for this claim is correct. 在上述 JSON 示例中,值为 access_as_applicationIn the previous JSON sample, the value is access_as_application.

  5. 选择“保存” 。Select Save.

后续步骤Next steps