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

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

请参阅快速入门:将应用程序注册到 Microsoft 标识平台,了解注册应用的步骤。See Quickstart: Register an application with the Microsoft identity platform for the common steps for registering an app.

接受的令牌版本Accepted token version

Microsoft 标识平台终结点可以发出两种类型的令牌:v1.0 令牌和 v2.0 令牌。The Microsoft identity platform endpoint can issue two types of tokens: v1.0 tokens and v2.0 tokens. 有关这些令牌的详细信息,请参阅访问令牌For more information about these tokens, see Access tokens. 接受的令牌版本取决于创建应用程序时选择的“支持的帐户类型”: The accepted token version depends on the Supported account types you chose when you created your application:

创建应用程序后,可以按以下步骤确定或更改接受的令牌版本: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 the Manifest for your app.
  2. 在清单中搜索 "accessTokenAcceptedVersion"In the manifest, search for "accessTokenAcceptedVersion". 请注意其值为 2Note that its value is 2. 此属性让 Azure Active Directory (Azure AD) 知道 Web API 接受 v2.0 令牌。This property specifies to Azure Active Directory (Azure AD) that the web API accepts v2.0 tokens. 如果该值为 null,则接受的令牌版本为 v1.0。If the value is null, the accepted token version is v1.0.
  3. 如果更改了令牌版本,请选择“保存”。 If you've changed the token version, select Save.

Note

Web API 会指定它所接受的令牌版本(v1.0 或 v2.0)。The web API specifies which token version (v1.0 or v2.0) it accepts. 当客户端从 Microsoft 标识平台 v2.0 终结点请求 Web API 的令牌时,所获得的令牌会指示哪个版本是 Web API 可以接受的。When clients request a token for your web API from the Microsoft identity platform (v2.0) endpoint, they'll get a token that indicates which version is accepted by the web API.

无重定向 URINo redirect URI

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

公开 APIExpose an API

特定于 Web API 的另一设置是公开的 API 和公开的作用域Another setting specific to web APIs is the exposed API and the exposed scopes.

资源 URI 和作用域Resource URI and scopes

范围通常采用 resourceURI/scopeName 格式。Scopes are usually in the form resourceURI/scopeName. 对于 Microsoft Graph,范围具有类似于 User.Read 的快捷方式。For Microsoft Graph, the scopes have shortcuts like User.Read. 此字符串是 https://microsoftgraph.chinacloudapi.cn/user.read 的快捷方式。This string is a shortcut for https://microsoftgraph.chinacloudapi.cn/user.read.

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

  • 资源 URI。The resource URI. 默认情况下,门户会建议使用 api://{clientId}By default, the portal recommends that you to use api://{clientId}. 此资源 URI 是唯一的,但不是用户可读的。This resource URI is unique, but it's not human readable. 可以更改它,但请确保新值是唯一的。You can change it, but make sure the new value is unique.
  • 一个或多个范围。 One or more scopes. (对于客户端应用程序,它们会显示为 Web API 的委托权限。) (To client applications, they'll show up as delegated permissions for your web API.)
  • 一个或多个应用角色。 One or more app roles. (对于客户端应用程序,它们会显示为 Web API 的应用程序权限。) (To client applications, they'll show up as application permissions for your web API.)

范围还会显示在呈现给应用的最终用户的许可屏幕上。The scopes are also displayed on the consent screen that's presented to end users of your app. 因此,需提供用于描述范围的相应字符串:So you'll need to provide the corresponding strings that describe the scope:

  • 如最终用户所见。As seen by the end user.
  • 如租户管理员所见,谁能授予管理员许可。As seen by the tenant admin, who can grant admin consent.

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

  1. 在应用程序注册中选择“公开 API”部分。 Select the Expose an API section 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. 输入以下参数:Enter these parameters:
    • 对于“范围名称”,请使用 access_as_userFor Scope name, use access_as_user.
    • 对于“谁能许可”,请确保选择“管理员和用户”。 For Who can consent, make sure Admins and users is selected.
    • 在“管理员许可显示名称”中,输入“以用户身份访问 TodoListService”。 In Admin consent display name, enter Access TodoListService as a user.
    • 在“管理员许可说明”中,输入“以用户身份访问 TodoListService Web API”。 In Admin consent description, enter Accesses the TodoListService Web API as a user.
    • 在“用户许可显示名称”中,输入“以用户身份访问 TodoListService”。 In User consent display name, enter Access TodoListService as a user.
    • 在“用户许可说明”中,输入“以用户身份访问 TodoListService Web API”。 In User consent description, enter Accesses the TodoListService Web API as a user.
    • 将“状态”始终设置为“已启用” 。Keep State set to Enabled.
    • 选择“添加作用域”。 Select Add scope.

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

本部分介绍如何注册受保护的 Web API,使其可由守护程序应用安全调用。In this section, you'll learn how to register your protected web API so it can be securely called by daemon apps.

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

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

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

  1. 在应用程序的应用程序注册中选择“清单”。 In the application registration for your application, select Manifest.
  2. 编辑清单:找到 appRoles 设置,然后添加一个或多个应用程序角色。Edit the manifest by locating the appRoles setting and adding one or more application roles. 以下示例 JSON 块中提供了角色定义。The role definition is provided in the following sample JSON block. 仅将 allowedMemberTypes 保留设置为 "Application"Leave the allowedMemberTypes set to "Application" only. 确保 id 是唯一的 GUID,且 displayNamevalue 不包含空格。Make sure the id is a unique GUID and that displayName and value don't contain spaces.
  3. 保存清单。Save the manifest.

以下示例显示了 appRoles 的内容。The following sample shows the contents of appRoles. id 可以是任何唯一的 GUID。)(The 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. (这是开发人员公开应用程序权限的方式。)但是,你也可以将 Azure AD 配置为仅向租户管理员批准的、可访问你的 API 的应用颁发 Web API 的令牌。(That's the developer way to expose application permissions.) But you can also configure Azure AD to issue a token for your web API only to apps that are approved by the tenant admin to access your API. 若要添加此增强的安全性:To add this increased security:

  1. 在应用注册的应用“概述”页上的“本地目录中的托管应用程序”下,选择包含应用名称的链接。 On the app Overview page for your app registration, select the link with the name of your app under Managed application in local directory. 此字段的标题可能已截断。The title for this field might be truncated. 例如,你可能会看到“...中的托管应用程序”。 You might, for example, see Managed application in ...

    Note

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

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

  3. 如果希望 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.

    Important

    如果将“需要用户分配?”设置为“是”,当客户端请求 Web API 的访问令牌时,Azure AD 会检查这些客户端的应用角色分配。 If you set User assignment required? to Yes, Azure AD will check the app role assignments of clients when they request an access token for the web API. 如果客户端未分配到任何应用角色,Azure AD 将返回错误 invalid_client: AADSTS501051: Application <application name> is not assigned to a role for the <web API>If the client isn't assigned to any app roles, Azure AD will return the error 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 (that is, any client using the client credentials flow) will be able to obtain an access token for the API just by specifying its audience. 任何应用程序都可以访问 API,而无需请求其权限。Any application will be able to access the API without having to request permissions for it. 但是,如上一部分中所述,Web API 始终可以验证应用程序是否具有适当的角色(由租户管理员授权)。But your web API can always, as explained in the previous section, verify that the application has the right role (which is authorized by the tenant admin). API 的验证方式是验证访问令牌是否包含角色声明,以及此声明的值是否正确。The API performs this verification by validating that the access token has a roles claim and that the value for this claim is correct. (在本例中,该值为 access_as_application。)(In our case, the value is access_as_application.)

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

后续步骤Next steps