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

与 Microsoft 标识平台集成的应用程序遵循的授权模型可让用户和管理员控制数据的访问方式。Applications that integrate with the Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. 授权模型的实现已在 Microsoft 标识平台上更新。The implementation of the authorization model has been updated on the Microsoft identity platform. 它更改了应用必须与 Microsoft 标识平台交互的方式。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.

范围和权限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 托管资源的一些示例:Here are some examples of Microsoft web-hosted resources:

  • Microsoft Graph: https://microsoftgraph.chinacloudapi.cnMicrosoft Graph:
  • Microsoft 365 邮件 API: 365 Mail API:
  • Azure Key Vault: Key Vault:

这同样适用于已与 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 功能的公开方式。Because of these types of permission definitions, 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.

将资源的功能分割成小的权限集时,可将第三方应用构建为只请求执行其功能所需的权限。When a resource's functionality is chunked into small permission sets, third-party apps can be built to request only the permissions that they need to perform their function. 用户和管理员能够知道应用可以访问哪些数据,Users and administrators can know what data the app can access. 因此可以更加确信应用不会出现恶意行为。And they can be more confident that the app isn't behaving with malicious intent. 开发人员应始终遵守“最低特权”原则,仅请求分配正常运行应用程序所需的权限。Developers should always abide by the principle 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 permission sets are called scopes. 它们通常也称为“权限”。They're also often referred to as permissions. 在 Microsoft 标识平台中,权限以字符串值形式表示。In the Microsoft identity platform, a permission is represented as a string value. 以 Microsoft Graph 为例,下面是每个权限的字符串值:For the Microsoft Graph example, here's the string value for each permission:

  • 使用 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, some high-privilege permissions can be granted only through administrator consent. 可以通过使用管理员同意终结点来请求或授予这些权限。They can be requested or granted by using the administrator consent endpoint. 请继续阅读以了解详细信息。Keep reading to learn more.

权限类型Permission types

Microsoft 标识平台支持两种类型的权限:委托的权限和应用程序权限 。The 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. 并向应用授予委托的权限,以便该应用在对目标资源进行调用时可充当登录的用户。The app is delegated permission to act as the signed-in user when it makes calls to the target resource.

    某些委托的权限可由非管理用户同意,Some delegated permissions can be consented to by nonadministrators. 但某些高特权权限需要管理员同意But some high-privileged permissions require administrator consent. 若要了解哪些管理员角色可以同意委托的权限,请参阅 Azure Active Directory (Azure AD) 中的管理员角色权限To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure Active Directory (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. 只有管理员才能同意应用程序权限。Only an administrator can consent to application permissions.

有效权限是你的应用在对目标资源发出请求时拥有的权限。Effective permissions are the permissions that your app has when it makes requests to the target resource. 必须了解委托权限、为应用授予的应用程序权限,以及在应用调用目标资源时为应用授予的有效权限之间的差异。It's important to understand the difference between the delegated permissions and application permissions that your app is granted, and the effective permissions your app is granted when it makes calls to the target resource.

  • 对于委托的权限,应用的有效权限是授予应用的委托权限(通过同意的方式)与当前登录用户特权的最低特权交集。For delegated permissions, the effective permissions of your app are the least-privileged intersection of the delegated permissions the app has been granted (by 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 can 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 can update the profile of every user in the organization. 但是,如果登录的用户没有管理员角色,则应用只能更新登录的用户的个人资料。However, if the signed-in user doesn't have an administrator role, your app can update only the profile of the signed-in user. 应用无法更新组织中其他用户的个人资料,因为它有权代表的用户没有这些特权。It can't update the profiles of other users in the organization because the user that it has permission to act on behalf of doesn't have those privileges.

  • 对于应用程序权限,应用的有效权限是权限默示的整个级别的特权。For application permissions, the effective permissions of your app are 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 标识平台实现具有一些已明确定义并托管在 Microsoft Graph 上的范围:openidemailprofileoffline_accessThe Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that are also hosted on Microsoft Graph: openid, email, profile, and offline_access. 不支持 addressphone OpenID Connect 范围。The address and phone OpenID Connect scopes aren't supported.

如果请求 OpenID Connect 范围和令牌,你会获得一个用于调用 UserInfo 终结点的令牌。If you request the OpenID Connect scopes and a token, you'll get a token to call the UserInfo endpoint.


如果应用使用 OpenID Connect 登录,它必须请求 openid 范围。If an app signs in by using OpenID Connect, it must request the openid scope. openid 范围作为“登录”权限显示在工作帐户同意页上。The openid scope appears on the work account consent page as the Sign you in permission.

应用可使用此权限以 sub 声明的形式接收用户的唯一标识符。By using this permission, an app can receive a unique identifier for the user in the form of the sub claim. 此权限还会向应用提供对 UserInfo 终结点的访问权限。The permission 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. 应用可以使用这些令牌进行身份验证。The app can use these tokens for authentication.


email 范围可与 openid 范围以及任何其他范围一起使用。The email scope can be used with the openid scope and any other scopes. 它以 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 your app uses the email scope, the app needs to be able to handle a case in which no email claim exists in the token.


profile 范围可与 openid 范围以及任何其他范围一起使用。The profile scope can be used with the openid scope and any other scope. 它向应用提供对大量有关该用户的信息的访问权限。It gives the app access to a large 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_tokens 参数中提供的 profile 声明的完整列表,请参阅 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_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.


目前,此权限会出现在所有同意页上,即使对于那些不提供刷新令牌的流(例如隐式流),也是这种情况。This permission currently appears on all consent pages, even for flows that don't provide a refresh token (such as the implicit flow). 该设置解决的是此类情况:客户端可以从隐式流开始,然后转到需要刷新令牌的代码流。This setup addresses scenarios where a client can begin within the implicit flow and then move to the code flow where a refresh token is expected.

在 Microsoft 标识平台上(向 v2.0 终结点发出的请求),应用程序必须显式请求 offline_access 范围才能接收刷新令牌。On the Microsoft identity platform (requests made to the v2.0 endpoint), your app must explicitly request the offline_access scope, to receive refresh tokens. 因此,在 OAuth 2.0 授权代码流中兑换授权代码时,你从 /token 终结点接收的只是访问令牌。So 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. 它的有效期通常为一小时。It 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.

有关如何获取及使用刷新令牌的详细信息,请参阅 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. (添加换行符是为了方便阅读)。(Line breaks are added for legibility.)


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 checks for a matching record of user consent. 如果用户过去未曾同意所请求权限的任何一项,并且管理员尚未代表整个组织同意这些权限,则 Microsoft 标识平台会请求用户授予请求的权限。If the user hasn't consented to any of the requested permissions in the past, and if the administrator hasn't consented to these permissions on behalf of the entire organization, the Microsoft identity platform asks the user to grant the requested permissions.

在此期间,offline_access(“维持对已授予访问权限的数据的访问权限”)权限和“登录并读取个人资料”)权限会自动包含在对应用程序的初始同意中。At this time, the offline_access ("Maintain access to data you have given it access to") permission and ("Sign you in and read your profile") permission are automatically included in the initial consent to an application. 这些权限通常是应用正常运行所需的权限。These permissions are generally required for proper app functionality. offline_access 权限为应用提供对刷新令牌的访问权限,而刷新令牌对本机应用和 Web 应用至关重要。The offline_access permission gives the app access to refresh tokens that are critical for native apps and web apps. 权限提供对 sub 声明的访问权限。The permission gives access to the sub claim. 它允许客户端或应用随时间推移正确标识用户并访问基本用户信息。It allows 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. 这样,用户在以后登录到应用程序时就无需再次同意。The user doesn't have to consent again when they later sign in to the application.

组织在购买应用程序的许可证或订阅时,通常需要主动设置该应用程序,以使其可供组织的所有成员使用。When an organization purchases a license or subscription for an application, the organization often 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 don'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 Microsoft resources can be set to admin-restricted. 下面是这些类型的权限的一些示例:Here are some examples of these kinds of permissions:

  • 使用 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 can't grant 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 scopes for admin-restricted permissions, an organization's administrator must consent to those scopes on behalf of the organization's users. 对于为自己无法授予的权限请求同意的用户,若要避免向其显示提示,可以让你的应用使用管理员同意终结点。To avoid displaying prompts to users that request consent for permissions they can't grant, your app can use the admin consent endpoint. 下一部分介绍管理员同意终结点。The admin consent endpoint is covered in the next section.

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

如果应用程序请求应用程序权限,而管理员通过管理员同意终结点授予这些权限,则不会代表任何特定用户进行此授权。If the application requests application permissions and an administrator grants these permissions through 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 used only by daemon services and other noninteractive applications that run in the background.

使用管理员同意终结点授予管理员同意后,操作便完成了。After you use the admin consent endpoint to grant admin consent, you're finished. 用户不需执行任何进一步的操作。Users don't need to take any further action. 授予管理员同意后,用户可以通过典型的授权流获得访问令牌。After admin consent is granted, users can get an access token through a typical auth flow. 生成的访问令牌将具有同意的权限。The resulting access token has the consented permissions.

当全局管理员使用你的应用程序并被定向到授权终结点时,Microsoft 标识平台会检测用户的角色,When a Global Administrator uses your application and is directed to the authorize endpoint, the Microsoft identity platform detects the user's role. 并询问全局管理员是否要代表整个租户同意你请求的权限。It asks if the Global Administrator wants to consent on behalf of the entire tenant for the permissions you requested. 你可以改用一个专用的管理员同意终结点,这样就可以主动请求管理员代表整个租户授予权限。You could instead use a dedicated admin consent endpoint to proactively request an administrator to grant permission on behalf of the entire tenant. 请求应用程序权限时,也必须使用此终结点。This endpoint is also necessary for requesting application permissions. 不能使用授权终结点来请求应用程序权限。Application permissions can't be requested by 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 operation is high privilege. 仅当对于你的方案而言为必需时才应使用。Use the operation only if necessary for your scenario.

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

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

在应用注册门户中,应用程序可以列出其所需的权限,包括委托的权限和应用程序权限。In the app registration portal, applications can list the permissions they require, including both delegated permissions and application permissions. 此设置允许使用 /.default 范围和 Azure 门户的“授予管理员同意”选项。This setup allows the use of the /.default scope and the Azure portal's Grant admin consent option.

通常,这些权限应该是为给定的应用程序静态定义的。In general, the permissions should be statically defined for a given application. 它们应该是应用会以动态或增量方式请求的权限的超集。They should be a superset of the permissions that the app will request dynamically or incrementally.


只能通过使用 /.default 来请求应用程序权限。Application permissions can be requested only through the use of /.default. 因此,如果应用需要应用程序权限,请确保这些权限在应用注册门户中列出。So if your app needs application permissions, make sure they're listed in the app registration portal.

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

  1. Azure 门户 - 应用注册 快速入门体验中转到你的应用程序。Go to your application in the Azure portal - App registrations quickstart experience.
  2. 选择一个应用程序,或创建一个应用(如尚未创建)。Select an application, or create an app if you haven't already.
  3. 在应用程序的“概述”页的“管理”下,选择“API 权限” > “添加权限”。 On the application's Overview page, under Manage, select API Permissions > Add a permission.
  4. 从可用 API 的列表中选择“Microsoft Graph”。Select Microsoft Graph from the list of available APIs. 然后添加应用所需的权限。Then add the permissions that your app requires.
  5. 选择“添加权限”。Select Add Permissions.

在构建使用管理员许可终结点的应用程序时,应用通常需要一个页面或视图,使管理员能够批准应用的权限。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.
  • 专用的“连接”流。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 account or school account.

将用户登录到应用时,可以先确定管理员所属的组织,然后要求管理员批准所需的权限。When you sign the user in to your app, you can identify the organization to which the admin belongs before you ask them to approve the necessary permissions. 尽管严格说来此步骤不是必需的,但它有助于为组织用户带来更直观的体验。Although this step isn't strictly necessary, it can help you create a more intuitive experience for your organizational users.

若要将用户登录,请遵循 Microsoft 标识平台协议教程To sign the user in, follow the 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.
参数Parameter 条件Condition 说明Description
tenant 必须Required 要向其请求权限的目录租户。The directory tenant that you want to request permission from. 可使用 GUID 或易记名称格式提供它,It can be provided in a GUID or friendly name format. 也可以采用常规方式使用组织来引用它,如示例所示。Or it can be generically referenced with organizations, as seen in the example.
client_id 必须Required Azure 门户 - 应用注册体验分配给应用的应用程序(客户端)ID。The 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.
scope 必须Required 定义应用程序请求的权限集。Defines the set of permissions being requested by the application. 范围可以是静态范围(使用 /.default),也可以是动态范围。Scopes can be either static (using /.default) or dynamic. 此集可以包括 OpenID Connect 范围(openidprofileemail)。This set can include the OpenID Connect scopes (openid, profile, email). 如果需要应用程序权限,必须使用 /.default 来请求静态配置的权限列表。If you need application permissions, you must use /.default to request the statically configured list of permissions.

此时,Azure AD 要求租户管理员登录,以完成请求。At this point, Azure AD requires a tenant administrator to sign in to complete the request. 系统会要求管理员批准你在 scope 参数中请求的所有权限。The administrator is asked to approve all the permissions that you requested in the scope parameter. 如果你使用了静态 (/.default) 值,则它的功能将类似于 v1.0 管理员同意终结点,并且它会请求对应用所需权限中找到的所有范围的同意。If you used a static (/.default) value, it will function like the v1.0 admin consent endpoint and request consent for all scopes found in the required permissions for the app.

成功的响应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 doesn't 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. 它还可用于对错误做出响应。It can also 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 the 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
Content-Type: application/json

    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "",
    "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 do 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. /.default 范围是内置的,适用于每个引用在应用程序注册时配置的权限静态列表的应用程序。The /.default scope is built in for every application that refers to the static list of permissions configured on the application registration.

scope 值为 时,其作用与 v1.0 终结点上的 resource= 相同。A scope value of is functionally the same as resource= on the v1.0 endpoint. 在请求中指定 范围即表示应用程序在请求一个访问令牌,该令牌包含你在应用注册门户中为应用选择的每个 Microsoft Graph 权限的范围。By specifying the scope in its request, your application is requesting an access token that includes scopes for every Microsoft Graph permission you've selected for the app in the app registration portal. 范围是使用资源 URI 和 /.default 构造的。The scope is constructed by using the resource URI and /.default. 因此,如果资源 URI 为,则请求的范围为 if the resource URI is, the scope requested is 有关必须包含另一个斜杠才能正确请求令牌的情况,请参阅有关尾随斜杠的部分For cases where you must include a second slash to correctly request the token, see the section about trailing slashes.

/.default 范围可用于任何 OAuth 2.0 流,The /.default scope can be used in any OAuth 2.0 flow. 但在代理流客户端凭据流中是必需的。But it's necessary in the On-Behalf-Of flow and client credentials flow. 在使用 v2 管理员同意终结点来请求应用程序权限时,你也需要它。You also need it when you use the v2 admin consent endpoint to request application permissions.

客户端不能在单个请求中合并静态同意 (/.default) 和动态同意。Clients can't combine static (/.default) consent and dynamic consent in a single request. 因此 scope= 会导致错误,因为它合并了范围类型。So scope= results in an error because it combines 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 that the application registered, regardless of the resource. 如果它已作为请求的一部分包含在内,/.default 范围会返回一个令牌,该令牌包含已请求的资源的范围。If it's included as part of the request, the /.default scope returns a token that contains the scopes for the resource requested.

/.default 范围在功能上等同于以 resource 为中心的 v1.0 终结点的行为。The /.default scope is functionally identical to the behavior of the resource-centric v1.0 endpoint. 它也带有 v1.0 终结点的同意行为。It carries the consent behavior of the v1.0 endpoint as well. 也就是说,仅当用户在客户端和资源之间未授予任何权限的情况下,/.default 才触发同意提示。That is, /.default triggers a consent prompt only if the user has granted no permission between the client and the resource.

如果存在任何此类同意,则返回的令牌会包含用户为该资源授予的所有范围。If any such consent exists, the returned token contains all scopes the user granted for that resource. 但是,如果尚未授予任何权限,或者已提供了 prompt=consent 参数,则会对客户端应用程序注册的所有范围显示同意提示。However, if no permission has been granted or if the prompt=consent parameter has been provided, a consent prompt is shown for all scopes that the client application registered.

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

在此示例中,用户或租户管理员向客户端授予了 Microsoft Graph 权限。In this example, the user or a tenant administrator has granted the and Microsoft Graph permissions to the client.

如果客户端请求 scope=,则不会显示任何同意提示,不管客户端应用程序已为 Microsoft Graph 注册的权限的内容如何。If the client requests scope=, no consent prompt is shown, regardless of the contents of the client application's registered permissions for Microsoft Graph. 返回的令牌包含范围 mail.readuser.readThe returned token contains the scopes and

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

在此示例中,用户尚未在客户端和 Microsoft Graph 之间授予同意。In this example, the user hasn't granted consent between the client and Microsoft Graph. 客户端已针对权限 进行注册。The client has registered for the permissions and 它还针对 Azure Key Vault 范围 进行了注册。It has also registered for the Azure Key Vault scope

当客户端请求用于 scope= 的令牌时,用户会看到针对 范围、 范围和 Key Vault user_impersonation 范围的同意页面。When the client requests a token for scope=, the user sees a consent page for the scope, the scope, and the Key Vault user_impersonation scopes. 返回的令牌仅包含 范围。The returned token contains only the and scopes. 它只能针对 Microsoft Graph 进行使用。It can be used only against Microsoft Graph.

示例 3:用户已同意,客户端请求更多范围Example 3: The user has consented, and the client requests more scopes

在此示例中,用户已为客户端许可 mail.readIn this example, the user has already consented to for the client. 客户端已针对 范围进行注册。The client has registered for the scope.

当客户端通过使用 scope= 请求令牌并通过 prompt=consent 请求同意时,用户会看到一个同意页面,该页面显示由应用程序注册的所有权限(且仅显示这些权限)。When the client requests a token by using scope= and requests consent through prompt=consent, the user sees a consent page for all (and only) the permissions that the application registered. 范围在同意页面上,但 不在。The scope is on the consent page but isn't. 返回的令牌用于 Microsoft Graph。The token returned is for Microsoft Graph. 它包含 mail.readcontacts.readIt contains and

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

在某些情况下,客户端可以请求其自己的 /.default 范围。In some cases, a client can request its own /.default scope. 以下示例演示了这种情况。The following example demonstrates this scenario.

// Line breaks are for legibility only.

response_type=token            //Code or a hybrid flow is also possible here

此代码示例为所有已注册的权限生成同意页,前提是前面有关同意和 /.default 的说明适用于此方案。This code example produces a consent page for all registered permissions if the preceding descriptions of consent and /.default apply to the scenario. 然后,此代码返回 id_token,而不是访问令牌。Then the code returns an id_token, rather than an access token.

此行为适合某些从 Azure AD 身份验证库 (ADAL) 迁移到 Microsoft 身份验证库 (MSAL) 的旧客户端。This behavior accommodates some legacy clients that are moving from Azure AD Authentication Library (ADAL) to the Microsoft Authentication Library (MSAL). 此设置不应由面向 Microsoft 标识平台的新客户端使用。This setup shouldn't be used by new clients that target the Microsoft identity platform.

客户端凭据授权流和“/.default”Client credentials grant flow and /.default

/.default 的另一种用法是在非交互式应用程序(例如,使用客户端凭据授权流来调用 Web API 的守护程序应用)中请求应用程序权限(或角色)。Another use of /.default is to request application permissions (or roles) in a noninteractive application like a daemon app that uses the client credentials grant flow to call a web API.

若要为 Web API 创建应用程序权限(角色),请参阅在应用程序中添加应用角色To create application permissions (roles) for a web API, see Add app roles in your application.

客户端应用中的客户端凭据请求必须包含 scope={resource}/.defaultClient credentials requests in your client app must include scope={resource}/.default. 在这里,{resource} 是应用要调用的 Web API。Here, {resource} is the web API that your app intends to call. 不支持使用单个应用程序权限(角色)发出客户端凭据请求。Issuing a client credentials request by using individual application permissions (roles) is not supported. 为该 Web API 授予的所有应用程序权限(角色)都包含在返回的访问令牌中。All the application permissions (roles) that have been granted for that web API are included in the returned access token.

若要授予对所定义的应用程序权限的访问权限,包括为应用程序授予管理员同意,请参阅配置客户端应用程序以访问 Web APITo grant access to the application permissions you define, including granting admin consent for the application, see Configure a client application to access a web API.

尾部斜杠和 /.defaultTrailing slash and /.default

某些资源 URI 包含尾随正斜杠,例如不是。Some resource URIs have a trailing forward slash, for example, as opposed to 尾随斜杠可能导致令牌验证出现问题。The trailing slash can cause problems with token validation. 问题主要发生在为 Azure 资源管理器 ( 请求令牌时。Problems occur primarily when a token is requested for Azure Resource Manager ( 在这种情况下,资源 URI 上的尾随斜杠意味着请求令牌时必须存在此斜杠。In this case, a trailing slash on the resource URI means the slash must be present when the token is requested. 因此,在请求 的令牌并使用 /.default 时,必须请求注意双斜杠!)。So when you request a token for and use /.default, you must request (notice the double slash!). 一般情况下,如果你确认令牌被颁发,但 API 在应该接受令牌的情况下拒绝了它,请考虑添加另一个正斜杠并重试。In general, if you verify that the token is being issued, and if the token is being rejected by the API that should accept it, consider adding a second forward slash and trying again.

有关故障排除步骤,请参阅针对应用程序执行同意操作时出现意外错误For troubleshooting steps, see Unexpected error when performing consent to an application.

后续步骤Next steps