Microsoft 标识平台终结点中的权限和许可Permissions and consent in the Microsoft identity platform endpoint

适用于:Applies to:
  • Microsoft 标识平台终结点Microsoft identity platform endpoint

与 Microsoft 标识平台集成的应用程序遵循的授权模型可让用户和管理员控制数据的访问方式。Applications that integrate with Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. 该授权模型的实现已在 Microsoft 标识平台终结点中更新,它改变了应用与 Microsoft 标识平台交互的方式。The implementation of the authorization model has been updated on the Microsoft identity platform endpoint, and it changes how an app must interact with the Microsoft identity platform. 本文介绍此授权模型的基本概念,包括范围、权限和许可。This article covers the basic concepts of this authorization model, including scopes, permissions, and consent.

Note

Microsoft 标识平台终结点并非支持所有方案和功能。The Microsoft identity platform endpoint does not support all scenarios and features. 若要确定是否应使用 Microsoft 标识平台终结点,请阅读 Microsoft 标识平台限制To determine whether you should use the Microsoft identity platform endpoint, read about Microsoft identity platform limitations.

范围和权限Scopes and permissions

Microsoft 标识平台实现 OAuth 2.0 授权协议。The Microsoft identity platform implements the OAuth 2.0 authorization protocol. OAuth 2.0 是可让第三方应用代表用户访问 Web 托管资源的方法。OAuth 2.0 is a method through which a third-party app can access web-hosted resources on behalf of a user. 与 Microsoft 标识平台集成的任何 Web 托管资源都有一个资源标识符,也称为“应用程序 ID URI”。 Any web-hosted resource that integrates with the Microsoft identity platform has a resource identifier, or Application ID URI. 例如,Microsoft 的部分 Web 托管资源包括:For example, some of Microsoft's web-hosted resources include:

  • Microsoft Graph: https://microsoftgraph.chinacloudapi.cnMicrosoft Graph: https://microsoftgraph.chinacloudapi.cn
  • Office 365 邮件 API:https://outlook.office.comOffice 365 Mail API: https://outlook.office.com
  • Azure AD Graph:https://graph.chinacloudapi.cnAzure AD Graph: https://graph.chinacloudapi.cn

Note

我们强烈建议使用 Microsoft Graph,而不要使用 Azure AD Graph、Office 365 邮件 API 等。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph, Office 365 Mail API, etc.

这同样适用于已与 Microsoft 标识平台集成的任何第三方资源。The same is true for any third-party resources that have integrated with the Microsoft identity platform. 以上任意资源还可以定义一组可用于将该资源的功能划分成较小区块的权限。Any of these resources also can define a set of permissions that can be used to divide the functionality of that resource into smaller chunks. 例如, Microsoft Graph 已定义执行以下任务及其他任务所需的权限:As an example, Microsoft Graph has defined permissions to do the following tasks, among others:

  • 读取用户的日历Read a user's calendar
  • 写入用户的日历Write to a user's calendar
  • 以用户身份发送邮件Send mail as a user

通过定义这些类型的权限,资源可以更精细地控制其数据以及 API 功能的公开方式。By defining these types of permissions, the resource has fine-grained control over its data and how API functionality is exposed. 第三方应用可以从用户和管理员请求这些权限,只有在用户或管理员批准该请求之后,应用才能代表用户访问或处理数据。A third-party app can request these permissions from users and administrators, who must approve the request before the app can access data or act on a user's behalf. 通过将资源的功能分割成较小的权限集,可将第三方应用构建为只请求所需的特定权限来执行其功能。By chunking the resource's functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. 用户和管理员可以确切地知道应用有权访问哪些数据,并且他们可以更加确信应用不会怀有恶意的企图。Users and administrators can know exactly what data the app has access to, and they can be more confident that it isn't behaving with malicious intent. 开发人员应始终遵守“最低特权”的概念,仅请求分配正常运行应用程序所需的权限。Developers should always abide by the concept of least privilege, asking for only the permissions they need for their applications to function.

在 OAuth 2.0 中,这些类型的权限称为“范围” 。In OAuth 2.0, these types of permissions are called scopes. 它们通常也称为“权限”。 They are also often referred to as permissions. 权限在 Microsoft 标识平台中以字符串值表示。A permission is represented in the Microsoft identity platform as a string value. 仍以 Microsoft Graph 为例,每个权限的字符串值为:Continuing with the Microsoft Graph example, the string value for each permission is:

  • 使用 Calendars.ReadRead a user's calendar by using Calendars.Read
  • 使用 Calendars.ReadWriteWrite to a user's calendar by using Calendars.ReadWrite
  • 使用 Mail.SendSend mail as a user using by Mail.Send

应用往往是通过在发往 Microsoft 标识平台授权终结点的请求中指定范围来请求这些权限。An app most commonly requests these permissions by specifying the scopes in requests to the Microsoft identity platform authorize endpoint. 但是,某些高特权权限只能通过管理员许可来授予,并且是使用管理员许可终结点来请求/授予的。However, certain high privilege permissions can only be granted through administrator consent and requested/granted using the administrator consent endpoint. 请继续阅读了解更多信息。Read on to learn more.

权限类型Permission types

Microsoft 标识平台支持两种类型的权限:委托的权限应用程序权限Microsoft identity platform supports two types of permissions: delegated permissions and application permissions.

  • 委托的权限由包含登录用户的应用使用。Delegated permissions are used by apps that have a signed-in user present. 对于这些应用,用户或管理员需许可应用请求的权限,并向应用授予委托的权限,以便在对目标资源发出调用时,该应用可充当登录的用户。For these apps, either the user or an administrator consents to the permissions that the app requests, and the app is delegated permission to act as the signed-in user when making calls to the target resource. 某些委托的权限可由非管理用户许可,但某些更高特权的权限需要管理员许可Some delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent. 若要了解哪些管理员角色可以同意委托的权限,请参阅 Azure AD 中的管理员角色权限To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

  • 应用程序权限由无需存在登录用户即可运行的应用使用;例如,以后台服务或守护程序形式运行的应用。Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. 应用程序权限只能由管理员许可Application permissions can only be consented by an administrator.

有效权限是应用在对目标资源发出请求时拥有的权限。 Effective permissions are the permissions that your app will have when making requests to the target resource. 在对目标资源发出调用时,必须了解应用授予的委托权限和应用程序权限与其有效权限之间的差别。It's important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to the target resource.

  • 对于委托的权限,应用的有效权限是(通过许可)授予应用的委托权限与当前登录用户的特权的最低特权交集。 For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. 应用的特权永远不会超过登录用户的特权。Your app can never have more privileges than the signed-in user. 在组织内部,可以通过策略或者一个或多个管理员角色的成员身份来确定登录用户的特权。Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. 若要了解哪些管理员角色可以同意委托的权限,请参阅 Azure AD 中的管理员角色权限To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

    例如,假设为应用授予了 Microsoft Graph 中的 User.ReadWrite.All 委托权限。For example, assume your app has been granted the User.ReadWrite.All delegated permission. 此权限在名义上会授予应用读取和更新组织中每个用户的个人资料的权限。This permission nominally grants your app permission to read and update the profile of every user in an organization. 如果登录用户是全局管理员,则应用可以更新组织中每个用户的个人资料。If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. 但是,如果登录用户不是充当管理员角色,则应用只能更新登录用户的个人资料。However, if the signed-in user isn't in an administrator role, your app will be able to update only the profile of the signed-in user. 它无法更新组织中其他用户的个人资料,因为该应用有权代表的用户没有这些特权。It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.

  • 对于应用程序权限,应用的有效权限是权限默示的完整特权级别。 For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. 例如,拥有 User.ReadWrite.All 应用程序权限的应用可以更新组织中每个用户的个人资料。For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

OpenID Connect 范围OpenID Connect scopes

OpenID Connect 的 Microsoft 标识平台实现有一些明确定义但未应用到指定资源的范围 - openidemailprofileoffline_accessThe Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that do not apply to a specific resource: openid, email, profile, and offline_access. 不支持 addressphone OpenID Connect 范围。The address and phone OpenID Connect scopes are not supported.

openidopenid

如果应用使用 OpenID Connect 执行登录,则必须请求 openid 范围。If an app performs sign-in by using OpenID Connect, it must request the openid scope. openid 范围作为“登录”权限显示在工作帐户许可页上。The openid scope shows on the work account consent page as the "Sign you in" permission. 应用可使用此权限以 sub 声明的形式接收用户的唯一标识符。With this permission, an app can receive a unique identifier for the user in the form of the sub claim. 它还会向应用提供对 UserInfo 终结点的访问权限。It also gives the app access to the UserInfo endpoint. 可以在 Microsoft 标识平台令牌终结点中使用 openid 范围来获取 ID 令牌,应用可以使用该令牌进行身份验证。The openid scope can be used at the Microsoft identity platform token endpoint to acquire ID tokens, which can be used by the app for authentication.

电子邮件email

email 范围可与 openid 范围和任何其他范围一起使用。The email scope can be used with the openid scope and any others. 它以 email 声明的形式向应用提供对用户主要电子邮件地址的访问权限。It gives the app access to the user's primary email address in the form of the email claim. 仅当某个电子邮件地址与用户帐户相关联(并非总是如此)时, email 声明才包含在令牌中。The email claim is included in a token only if an email address is associated with the user account, which isn't always the case. 如果使用 email 范围,则应用应准备好处理 email 声明不存在于令牌中的情况。If it uses the email scope, your app should be prepared to handle a case in which the email claim does not exist in the token.

个人资料profile

profile 范围可与 openid 范围和任何其他范围一起使用。The profile scope can be used with the openid scope and any others. 它向应用提供对大量用户信息的访问权限。It gives the app access to a substantial amount of information about the user. 可访问的信息包括但不限于用户的名字、姓氏、首选用户名和对象 ID。The information it can access includes, but isn't limited to, the user's given name, surname, preferred username, and object ID. 有关指定用户的 id_token 参数中可用配置文件声明的完整列表,请参阅 id_tokens 参考For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the id_tokens reference.

offline_accessoffline_access

offline_access 范围 可让应用长时间代表用户访问资源。The offline_access scope gives your app access to resources on behalf of the user for an extended time. 在同意页上,此范围将显示为“维持对已授予访问权限的数据的访问”权限。On the consent page, this scope appears as the "Maintain access to data you have given it access to" permission. 用户批准 offline_access 范围后,应用可接收来自 Microsoft 标识平台令牌终结点的刷新令牌。When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. 刷新令牌的生存期较长。Refresh tokens are long-lived. 旧的访问令牌过期时,应用可以获取新的访问令牌。Your app can get new access tokens as older ones expire.

如果应用未显式请求 offline_access 范围,则收不到刷新令牌。If your app does not explicitly request the offline_access scope, it won't receive refresh tokens. 这意味着,在 OAuth 2.0 授权代码流中兑换授权代码时,只能从 /token 终结点接收访问令牌。This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll receive only an access token from the /token endpoint. 访问令牌在短期内有效。The access token is valid for a short time. 访问令牌的有效期通常为一小时。The access token usually expires in one hour. 到时,应用需要将用户重定向回到 /authorize 终结点以获取新的授权代码。At that point, your app needs to redirect the user back to the /authorize endpoint to get a new authorization code. 此重定向期间,用户可能需要再次输入其凭据或重新同意权限,具体取决于应用类型。During this redirect, depending on the type of app, the user might need to enter their credentials again or consent again to permissions. 当服务器自动请求 offline_access 范围时,客户端必须继续请求它才能收到刷新令牌。While the offline_access scope is automatically requested by the server, your client must still request it in order to receive the refresh tokens.

有关如何获取及使用刷新令牌的详细信息,请参阅 Microsoft 标识平台协议参考For more information about how to get and use refresh tokens, see the Microsoft identity platform protocol reference.

OpenID Connect 或 OAuth 2.0 授权请求中,应用可以使用 scope 查询参数来请求所需的权限。In an OpenID Connect or OAuth 2.0 authorization request, an app can request the permissions it needs by using the scope query parameter. 例如,当用户登录应用程序时,应用发送如下示例所示的请求(包含换行符以便于阅读):For example, when a user signs in to an app, the app sends a request like the following example (with line breaks added for legibility):

GET https://login.partner.microsoftonline.cn/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fmicrosoftgraph.chinacloudapi.cn%2Fcalendars.read%20
https%3A%2F%2Fmicrosoftgraph.chinacloudapi.cn%2Fmail.send
&state=12345

scope 参数是应用程序所请求的委托权限列表(以空格分隔)。The scope parameter is a space-separated list of delegated permissions that the app is requesting. 将权限值附加到资源的标识符(应用程序 ID URI)可指示权限。Each permission is indicated by appending the permission value to the resource's identifier (the Application ID URI). 在该请求示例中,应用需要相应的权限来读取用户的日历,以及以用户身分发送邮件。In the request example, the app needs permission to read the user's calendar and send mail as the user.

在用户输入其凭据之后,Microsoft 标识平台终结点将检查是否有匹配的 用户许可记录。After the user enters their credentials, the Microsoft identity platform endpoint checks for a matching record of user consent. 如果用户未曾许可所请求权限的任何一项,并且管理员尚未代表整个组织许可这些权限,则 Microsoft 标识平台终结点将请求用户授予请求的权限。If the user has not consented to any of the requested permissions in the past, nor has an administrator consented to these permissions on behalf of the entire organization, the Microsoft identity platform endpoint asks the user to grant the requested permissions.

Note

在此期间,offline_access(“维持对已授予访问权限的数据的访问”)和 user.read(“登录并读取配置文件”)权限将自动包含在对应用程序的初始许可中。At this time, the offline_access ("Maintain access to data you have given it access to") and user.read ("Sign you in and read your profile") permissions are automatically included in the initial consent to an application. 这些权限通常是应用功能正常所必需 - offline_access 授予应用对刷新令牌(对本机和 Web 应用十分重要)的访问权限,而 user.read 授予对 sub 声明的访问权限,允许客户端或应用随时间推移正确标识用户并访问基本用户信息。These permissions are generally required for proper app functionality - offline_access gives the app access to refresh tokens, critical for native and web apps, while user.read gives access to the sub claim, allowing the client or app to correctly identify the user over time and access rudimentary user information.

显示工作帐户同意的示例屏幕截图

当用户批准权限请求时,会记录许可,使用户在后续登录到应用程序时无需再次许可。When the user approves the permission request, consent is recorded and the user doesn't have to consent again on subsequent sign-ins to the application.

组织购买应用程序的许可证或订阅时,需要主动设置组织所有成员使用的应用程序。Often, when an organization purchases a license or subscription for an application, the organization wants to proactively set up the application for use by all members of the organization. 在此过程中,管理员可以代表租户中的任何用户授予对该应用程序的许可。As part of this process, an administrator can grant consent for the application to act on behalf of any user in the tenant. 如果管理员为整个租户授予许可,则组织的用户不会看到该应用程序的许可页。If the admin grants consent for the entire tenant, the organization's users won't see a consent page for the application.

若要为租户中的所有用户请求许可委托的权限,应用可以使用管理员许可终结点。To request consent for delegated permissions for all users in a tenant, your app can use the admin consent endpoint.

此外,应用程序必须使用管理员许可终结点来请求应用程序权限。Additionally, applications must use the admin consent endpoint to request Application Permissions.

管理员限制的权限Admin-restricted permissions

可将 Microsoft 生态系统中的某些高特权权限设置为受管理员限制Some high-privilege permissions in the Microsoft ecosystem can be set to admin-restricted. 此类权限的示例包括:Examples of these kinds of permissions include the following:

  • 使用 User.Read.All 读取所有用户的完整个人资料Read all user's full profiles by using User.Read.All
  • 使用 Directory.ReadWrite.AllWrite data to an organization's directory by using Directory.ReadWrite.All
  • 使用 Groups.Read.All 读取组织目录中的所有组Read all groups in an organization's directory by using Groups.Read.All

尽管使用者用户可以授予应用程序对此类数据的访问权限,但组织用户会受到限制,无法授予对同一敏感公司数据集的访问权限。Although a consumer user might grant an application access to this kind of data, organizational users are restricted from granting access to the same set of sensitive company data. 如果应用程序向组织用户请求访问以下权限之一,用户会收到错误消息,指出他们未经授权,无法许可应用的权限。If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions.

如果应用需要访问组织的受管理员限制的范围,同样应该使用管理员许可终结点直接向公司管理员请求相关权限,如下所述。If your app requires access to admin-restricted scopes for organizations, you should request them directly from a company administrator, also by using the admin consent endpoint, described next.

如果应用程序请求高特权的委托权限,而管理员通过管理员许可终结点授予这些权限,则为租户中的所有用户授予许可。If the application is requesting high privilege delegated permissions and an administrator grants these permissions via the admin consent endpoint, consent is granted for all users in the tenant.

如果应用程序请求应用程序权限,而管理员通过管理员许可终结点授予这些权限,则不会代表任何特定用户进行此授权,If the application is requesting application permissions and an administrator grants these permissions via the admin consent endpoint, this grant isn't done on behalf of any specific user. 而是直接为客户端应用程序授予权限。 Instead, the client application is granted permissions directly. 这些类型的权限只由守护程序服务以及后台运行的其他非交互式应用程序使用。These types of permissions are only used by daemon services and other non-interactive applications that run in the background.

Note

请注意,在使用管理员同意终结点授予管理员同意后,你已经完成授予管理员同意,用户不需要执行任何其他操作。Please note after granting admin consent using the admin consent endpoint, you have finished granting admin consent and users do not need to perform any further additional actions. 授予管理员同意后,用户可以通过典型的授权流获得访问令牌,并且生成的访问令牌将具有同意的权限。After granting admin consent, users can get an access token via a typical auth flow and the resulting access token will have the consented permissions.

当公司管理员使用你的应用程序并定向到授权终结点时,Microsoft 标识平台将检测用户的角色,并询问他们是否要代表整个租户许可请求的权限。When a Company Administrator uses your application and is directed to the authorize endpoint, Microsoft identity platform will detect the user's role and ask them if they would like to consent on behalf of the entire tenant for the permissions you have requested. 但是,如果你想要主动请求管理员代表整个租户授予权限,则还可以使用一个专用的管理员许可终结点。However, there is also a dedicated admin consent endpoint you can use if you would like to proactively request that an administrator grants permission on behalf of the entire tenant. 请求应用程序权限(不能使用授权终结点来请求)时,也必须使用此终结点。Using this endpoint is also necessary for requesting Application Permissions (which can't be requested using the authorize endpoint).

如果你遵循了这些步骤,则应用就能为租户中的所有用户请求权限,包括受管理员限制的范围。If you follow these steps, your app can request permissions for all users in a tenant, including admin-restricted scopes. 这是一个高特权操作,只能根据方案的需要来执行。This is a high privilege operation and should only be done if necessary for your scenario.

若要查看实现这些步骤的代码示例,请参阅 受管理员限制的范围示例To see a code sample that implements the steps, see the admin-restricted scopes sample.

在应用注册门户中请求权限Request the permissions in the app registration portal

管理员许可不接受范围参数,因此,必须在应用程序的注册中以静态方式定义所请求的任何权限。The admin consent does not accept a scope parameter, so any permissions being requested must be statically defined in the application's registration. 通常,最佳做法是确保为给定应用程序静态定义的权限是它动态/增量请求的权限的超集。In general, it's best practice to ensure that the permissions statically defined for a given application are a superset of the permissions that it will be requesting dynamically/incrementally.

配置应用程序的静态请求权限列表To configure the list of statically requested permissions for an application

  1. Azure 门户 - 应用注册体验中转到你的应用程序,或创建一个应用(如果尚未创建)。Go to your application in the Azure portal - App registrations experience, or create an app if you haven't already.
  2. 找到“API 权限”部分 ,然后在“API 权限”中单击“添加权限”。Locate the API Permissions section, and within the API permissions click Add a permission.
  3. 从可用 API 列表中选择 Microsoft Graph,然后添加应用所需的权限。Select Microsoft Graph from the list of available APIs and then add the permissions that your app requires.
  4. 保存 应用注册。Save the app registration.

在构建使用管理员许可终结点的应用程序时,应用通常需要一个页面或视图,使管理员能够批准应用的权限。Typically, when you build an application that uses the admin consent endpoint, the app needs a page or view in which the admin can approve the app's permissions. 此页面可以是应用注册流的一部分、应用设置的一部分,或者专用的“连接”流。This page can be part of the app's sign-up flow, part of the app's settings, or it can be a dedicated "connect" flow. 在许多情况下,合理的结果是只有在用户使用工作或学校帐户登录后,应用才显示此“连接”视图。In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work or school account.

将用户登录到应用后,便可识别管理员所属的组织,然后要求他们批准必要的权限。When you sign the user into your app, you can identify the organization to which the admin belongs before asking them to approve the necessary permissions. 尽管在严格意义上不需要这样做,但这有助于为组织用户带来更直观的体验。Although not strictly necessary, it can help you create a more intuitive experience for your organizational users. 若要将用户登录,请遵循 Microsoft 标识平台协议教程To sign the user in, follow our Microsoft identity platform protocol tutorials.

向目录管理员请求权限Request the permissions from a directory admin

准备好向组织管理员请求权限时,可将用户重定向到 Microsoft 标识平台管理员许可终结点When you're ready to request permissions from your organization's admin, you can redirect the user to the Microsoft identity platform admin consent endpoint.

// Line breaks are for legibility only.

GET https://login.partner.microsoftonline.cn/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
// Pro tip: Try pasting the below request in a browser!
https://login.partner.microsoftonline.cn/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
参数Parameter 条件Condition 说明Description
tenant 必须Required 要向其请求权限的目录租户。The directory tenant that you want to request permission from. 可以采用 GUID 或友好名称格式提供或使用 common 以一般方式引用,如示例所示。Can be provided in GUID or friendly name format OR generically referenced with common as seen in the example.
client_id 必须Required Azure 门户 - 应用注册体验分配给应用的应用程序(客户端)IDThe Application (client) ID that the Azure portal - App registrations experience assigned to your app.
redirect_uri 必须Required 要向其发送响应,供应用处理的重定向 URI。The redirect URI where you want the response to be sent for your app to handle. 必须与在应用注册门户中注册的重定向 URI 之一完全匹配。It must exactly match one of the redirect URIs that you registered in the app registration portal.
state 建议Recommended 同样随令牌响应返回的请求中所包含的值。A value included in the request that will also be returned in the token response. 其可以是关于想要的任何内容的字符串。It can be a string of any content you want. 使用该状态可在身份验证请求出现之前,在应用中编码用户的状态信息,例如用户过去所在的页面或视图。Use the state to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

此时,Azure AD 会要求租户管理员进行登录来完成请求。At this point, Azure AD requires a tenant administrator to sign in to complete the request. 系统要求管理员批准在应用注册门户中针对应用请求的所有权限。The administrator is asked to approve all the permissions that you have requested for your app in the app registration portal.

成功的响应Successful response

如果管理员批准了应用的权限,成功响应如下所示:If the admin approves the permissions for your app, the successful response looks like this:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
参数Parameter 说明Description
tenant 向应用程序授予所请求权限的目录租户(采用 GUID 格式)。The directory tenant that granted your application the permissions it requested, in GUID format.
state 同样随令牌响应返回的请求中所包含的值。A value included in the request that also will be returned in the token response. 可以是所需的任何内容的字符串。It can be a string of any content you want. 该 state 用于在身份验证请求出现之前,于应用中编码用户的状态信息,例如之前所在的页面或视图。The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consent 将设置为 TrueWill be set to True.

错误响应Error response

如果管理员未批准应用的权限,失败响应如下所示:If the admin does not approve the permissions for your app, the failed response looks like this:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
参数Parameter 说明Description
error 可用于分类发生的错误类型与响应错误的错误码字符串。An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description 可帮助开发人员识别错误根本原因的具体错误消息。A specific error message that can help a developer identify the root cause of an error.

从管理员许可终结点收到成功响应后,应用便已获得所请求的权限。After you've received a successful response from the admin consent endpoint, your app has gained the permissions it requested. 接下来,可以请求所需的资源令牌。Next, you can request a token for the resource you want.

使用权限Using permissions

用户许可应用的权限之后,应用即可获取访问令牌,这些令牌表示应用以某种身份访问资源的权限。After the user consents to permissions for your app, your app can acquire access tokens that represent your app's permission to access a resource in some capacity. 访问令牌只能用于单个资源,但其内部编码了应用已获得的该资源的所有权限。An access token can be used only for a single resource, but encoded inside the access token is every permission that your app has been granted for that resource. 若要获取访问令牌,应用可以对 Microsoft 标识平台令牌终结点发出类似于以下请求:To acquire an access token, your app can make a request to the Microsoft identity platform token endpoint, like this:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.partner.microsoftonline.cn
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/mail.read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq..."
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

可在资源的 HTTP 请求中使用生成的访问令牌。You can use the resulting access token in HTTP requests to the resource. 该令牌可靠地向资源指明,应用已获得适当权限,可执行特定的任务。It reliably indicates to the resource that your app has the proper permission to perform a specific task.

有关 OAuth 2.0 协议以及如何获取访问令牌的详细信息,请参阅 Microsoft 标识平台终结点协议参考For more information about the OAuth 2.0 protocol and how to get access tokens, see the Microsoft identity platform endpoint protocol reference.

/.default 范围The /.default scope

可以使用 /.default 范围,帮助将应用从 v1.0 终结点迁移到 Microsoft 标识平台终结点。You can use the /.default scope to help migrate your apps from the v1.0 endpoint to the Microsoft identity platform endpoint. 这是每个引用应用程序注册时配置的权限静态列表的应用程序的内置范围。This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. 值为 scopehttps://microsoftgraph.chinacloudapi.cn/.default 从功能上与 v1.0 终结点 resource=https://microsoftgraph.chinacloudapi.cn 相同 - 也就是说,它请求具有 Microsoft Graph 上的范围的令牌,应用程序在 Azure 门户中已注册 Microsoft Graph。A scope value of https://microsoftgraph.chinacloudapi.cn/.default is functionally the same as the v1.0 endpoints resource=https://microsoftgraph.chinacloudapi.cn - namely, it requests a token with the scopes on Microsoft Graph that the application has registered for in the Azure portal.

/.default 范围可用于任何 OAuth 2.0 流,但在代理流客户端凭据流中很有必要。The /.default scope can be used in any OAuth 2.0 flow, but is necessary in the On-Behalf-Of flow and client credentials flow.

Note

客户端不能在单个请求中合并静态许可 (/.default) 和动态许可。Clients can't combine static (/.default) and dynamic consent in a single request. 因此,scope=https://microsoftgraph.chinacloudapi.cn/.default+mail.read 将因范围类型组合而导致错误。Thus, scope=https://microsoftgraph.chinacloudapi.cn/.default+mail.read will result in an error due to the combination of scope types.

/.default 范围也可触发 prompt=consent 的 v1.0 终结点行为。The /.default scope triggers the v1.0 endpoint behavior for prompt=consent as well. 它将请求应用程序所注册的所有权限的许可,而不考虑相关资源。It requests consent for all permissions registered by the application, regardless of the resource. 如果作为请求的一部分包含,/.default 范围将返回一个令牌,该令牌包含资源请求的范围。If included as part of the request, the /.default scope returns a token that contains the scopes for the resource requested.

由于 /.default 功能上等同于 resource-centric v1.0 终结点的行为,因此也附带了 v1.0 终结点的许可行为。Because /.default is functionally identical to the resource-centric v1.0 endpoint's behavior, it brings with it the consent behavior of the v1.0 endpoint as well. 也就是说,如果用户在客户端和资源之间未授予任何权限,则 /.default 仅触发许可提示。Namely, /.default only triggers a consent prompt if no permission has been granted between the client and the resource by the user. 如果存在任何此类许可,则将返回一个令牌,该令牌包含由该资源的用户授予的所有范围。If any such consent exists, then a token will be returned containing all scopes granted by the user for that resource. 但是,如果尚未授予任何权限,或未提供 prompt=consent 参数,则将对客户端应用程序注册的所有范围显示许可提示。However, if no permission has been granted, or the prompt=consent parameter has been provided, a consent prompt will be shown for all scopes registered by the client application.

示例 1:用户或租户管理员已授予权限Example 1: The user, or tenant admin, has granted permissions

用户(或租户管理员)已授予客户端 Microsoft Graph 权限 mail.readuser.readThe user (or a tenant administrator) has granted the client the Microsoft Graph permissions mail.read and user.read. 如果客户端发出 scope=https://microsoftgraph.chinacloudapi.cn/.default 请求,则不会显示任何许可提示,而不考虑针对 Microsoft Graph 的客户端应用程序注册权限的许可。If the client makes a request for scope=https://microsoftgraph.chinacloudapi.cn/.default, then no consent prompt will be shown regardless of the contents of the client applications registered permissions for Microsoft Graph. 将返回包含范围 mail.readuser.read 的令牌。A token would be returned containing the scopes mail.read and user.read.

示例 2:用户在客户端和资源之间未授予权限Example 2: The user hasn't granted permissions between the client and the resource

客户端和 Microsoft Graph 之间不存在任何用户许可。No consent for the user exists between the client and Microsoft Graph. 客户端已针对 user.readcontacts.read 权限,以及 Azure Key Vault 范围https://vault.azure.cn/user_impersonation注册。The client has registered for the user.read and contacts.read permissions, as well as the Azure Key Vault scope https://vault.azure.cn/user_impersonation. 当客户端请求用于 scope=https://microsoftgraph.chinacloudapi.cn/.default 的令牌时,用户将看到用于 user.readcontacts.read和 Key Vault user_impersonation 范围的许可屏幕。When the client requests a token for scope=https://microsoftgraph.chinacloudapi.cn/.default, the user will see a consent screen for the user.read, contacts.read, and the Key Vault user_impersonation scopes. 返回的令牌中将仅包含 user.readcontacts.read 范围。The token returned will have just the user.read and contacts.read scopes in it.

示例 3:用户已同意且客户端请求了其他范围Example 3: The user has consented and the client requests additional scopes

用户已针对客户端同意 mail.readThe user has already consented to mail.read for the client. 客户端已在其注册中注册 contacts.read 范围。The client has registered for the contacts.read scope in its registration. 当客户端使用 scope=https://microsoftgraph.chinacloudapi.cn/.default 发出令牌请求,并通过 prompt=consent 请求许可时,用户将看到一个许可屏幕,该屏幕仅显示由应用程序注册的所有权限。When the client makes a request for a token using scope=https://microsoftgraph.chinacloudapi.cn/.default and requests consent through prompt=consent, then the user will see a consent screen for only and all the permissions registered by the application. 许可屏幕中将显示 contacts.read,但不会显示 mail.readcontacts.read will be present in the consent screen, but mail.read will not. 返回的令牌将用于 Microsoft Graph,并且将包含 mail.readcontacts.readThe token returned will be for Microsoft Graph and will contain mail.read and contacts.read.

对客户端使用 /.default 范围Using the /.default scope with the client

/.default 范围的一种特殊情况是客户端请求其自己的 /.default 范围。A special case of the /.default scope exists where a client requests its own /.default scope. 以下示例演示了这种情况。The following example demonstrates this scenario.

// Line breaks are for legibility only.

GET https://login.partner.microsoftonline.cn/{tenant}/oauth2/v2.0/authorize?
response_type=token            //code or a hybrid flow is also possible here
&client_id=9ada6f8a-6d83-41bc-b169-a306c21527a5
&scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
&redirect_uri=https%3A%2F%2Flocalhost
&state=1234

这将产生显示所有已注册权限(如果根据许可和 /.default 的上述说明适用)的许可屏幕,然后返回 id_token,而不是访问令牌。This produces a consent screen for all registered permissions (if applicable based on the above descriptions of consent and /.default), then returns an id_token, rather than an access token. 此行为针对从 ADAL 迁移到 MSAL 的某些旧客户端存在,并且不得由面向 Microsoft 标识平台终结点的新客户端使用。This behavior exists for certain legacy clients moving from ADAL to MSAL, and should not be used by new clients targeting the Microsoft identity platform endpoint.

如果你或应用程序的用户在许可过程中看到意外的错误,请参阅以下文章获取故障排除步骤:对应用程序执行许可时发生意外错误If you or your application's users are seeing unexpected errors during the consent process, see this article for troubleshooting steps: Unexpected error when performing consent to an application.