请求通过同意许可

  • 项目

Microsoft 标识平台中的应用程序必须获得同意才能访问所需的资源或 API。 不同类型的同意更适合不同的应用场景。 为应用选择最佳同意方法将有助于用户和组织更成功。

在本文中，你将了解不同类型的同意，以及如何通过同意为你的应用程序请求权限。

在静态用户同意方案中，必须在 Microsoft Entra 管理门户的应用配置中指定应用所需的所有权限。 如果用户（或管理员，视情况而定）尚未对此应用授予同意，则 Microsoft 标识平台会提示用户提供同意。

静态权限还使管理员能够代表组织中的所有用户进行同意。

虽然依赖于静态许可和单个权限列表会让代码保持优雅简洁，但这也意味着你的应用将预先请求它可能需要的所有权限。 这可能会阻止用户和管理员批准应用的访问请求。

使用 Microsoft 标识平台终结点，可以忽略在 Microsoft Entra 管理门户中的应用程序注册信息中定义的静态权限。 而是能够以增量方式请求权限。 可以一开始请求最少的一组权限，然后随着时间的推移，当客户使用更多应用程序功能时，再请求更多权限。 为此，可以在请求访问令牌时，通过在 scope 参数中包含新的范围指定应用程序所需的范围 - 无需在应用程序注册信息中预定义这些范围。 如果用户尚未许可添加到请求的新范围，则系统会提示他们仅许可新的权限。 增量许可或动态许可仅适用于委托的权限，而不适用于应用程序权限。

允许应用程序通过 scope 参数动态请求权限可让开发人员完全控制用户的体验。 还可以将许可体验提前，并在一个初始授权请求中请求所有的权限。 如果应用程序需要大量的权限，则你可以在用户尝试使用应用程序的某些功能过程中，以递增方式向用户收集这些权限。

重要

动态同意可能很方便，但对需要管理员同意的权限而言，有很大的挑战。 门户的“应用注册”和“企业应用程序”边栏选项卡中的管理员同意体验在同意时不知道这些动态权限。 建议开发人员列出门户中应用程序所需的所有管理员特权。 这使租户管理员能够代表门户中所有用户同意一次。 用户无需在登录时完成这些权限的同意体验。 替代方法是对这些权限使用动态同意。 若要授予管理员同意，个人管理员可登录到应用，触发适当权限的同意提示，并在同意对话框中选择“整个组织的同意”。

在 OpenID Connect 或 OAuth 2.0 授权请求中，应用程序可以使用 scope 查询参数来请求它所需的权限。 例如，当用户登录应用时，应用程序会发送类似于以下示例的请求。 （添加换行符是为了方便阅读）。

GET https://login.partner.microsoftonline.cn/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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 参数是应用程序所请求的委托权限列表（以空格分隔）。 每个权限都是通过将权限值附加到资源的标识符（应用程序 ID URI）来指示的。 在请求示例中，应用程序需要相应的权限来读取用户的邮箱和以用户身份发送邮件。

在用户输入其凭据之后，Microsoft 标识平台将检查是否有匹配的用户同意记录。 如果用户过去未曾同意所请求权限的任何一项，并且管理员尚未代表整个组织同意这些权限，则 Microsoft 标识平台会请求用户授予请求的权限。

在以下示例中，offline_access（“维持对已授予访问权限的数据的访问权限”）权限和 User.Read（“登录并读取个人资料”）权限会自动包含在对应用程序的初始同意中。 这些权限是应用程序正常运行所需的权限。 offline_access 权限为应用程序提供对刷新令牌的访问权限，而刷新令牌对本机应用和 Web 应用至关重要。 User.Read 权限提供对 sub 声明的访问权限。 它允许客户端或应用程序随时间推移正确标识用户并访问基本用户信息。

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

当用户批准权限请求时，系统会记录同意。 这样，用户在以后登录到应用程序时就无需再次同意。

请求整个租户的同意需要管理员同意。 代表组织执行管理员同意仍需要为应用注册静态权限。 如果需要管理员代表整个组织授予同意，请在应用注册门户中设置这些权限。

当应用程序请求需要由管理员同意的委派权限时，用户会收到一条错误消息，指出他们无权同意应用的权限。 用户需要请求其管理员提供该应用的访问权限。 如果管理员授予整个租户的许可，则组织的用户不会看到应用程序的同意页，除非以前授予的权限被撤销或应用程序以增量方式请求新权限。

使用同一应用程序的管理员将看到管理员同意提示。 管理员同意提示将提供一个复选框，允许管理员代表整个租户的用户向应用程序授予对所请求数据的访问权限。 有关用户和管理员同意体验的详细信息，请参阅应用程序同意体验。

需要管理员同意的 Microsoft Graph 委派权限示例包括：

  • 使用 User.Read.All 读取用户的所有完整个人资料
  • 使用 Directory.ReadWrite.All 将数据写入组织的目录
  • 使用 Groups.Read.All 读取组织目录中的所有组

若要查看 Microsoft Graph 权限的完整列表，请参阅 Microsoft Graph 权限参考。

还可以将对自己的资源的权限配置为要求管理员同意。 有关如何添加需要管理员同意的范围的详细信息，请参阅添加需要管理员同意的范围。

某些组织可能会更改租户的默认用户同意策略。 当应用程序请求访问权限时，会根据这些策略对这些请求进行评估。 即使默认情况下不需要，用户也可能需要请求管理员同意。 若要了解管理员如何管理应用程序的同意策略，请参阅管理应用同意策略。

注意

在对 Microsoft 标识平台的授权、令牌或同意终结点请求中，如果在 scope 参数中省略资源标识符，则假定资源为 Microsoft Graph。 例如，scope=User.Read 相当于 https://microsoftgraph.chinacloudapi.cn/User.Read。

应用程序权限始终需要管理员同意。 应用程序权限没有用户上下文，并且不会代表任何特定用户完成同意授予。 而是直接向客户端应用程序授予权限，这些类型的权限仅限于后台运行的守护程序服务和其他非交互式应用程序使用。 管理员需要预先配置权限，并通过 Microsoft Entra 管理门户授予管理员同意。

如果请求权限的应用程序是多租户应用程序，则其应用程序注册仅存在于创建权限的租户中，因此无法在本地租户中配置权限。 如果应用程序请求的权限需要由管理员同意，则管理员需要代表用户同意。 若要同意这些权限，管理员需要登录到应用程序本身，以便触发管理员同意登录体验。 若要了解如何为多租户应用程序设置管理员同意体验，请参阅启用多租户登录

管理员可以使用以下选项向应用程序授予同意。

通常，生成需要管理员同意的应用程序时，应用程序需要一个页面/视图，使管理员能够批准应用的权限。 此页可以是：

  • 应用的注册流的一部分。
  • 应用的设置的一部分。
  • 专用的“连接”流。

在许多情况下，合理的结果是应用程序只在用户使用工作 Microsoft 帐户或学校 Microsoft 帐户登录之后才显示此“连接”视图。

将用户登录到应用时，可以先确定管理员所属的组织，然后要求管理员批准所需的权限。 尽管严格说来此步骤不是必需的，但它有助于为组织用户带来更直观的体验。

若要将用户登录，请遵循 Microsoft 标识平台协议教程。

在应用注册门户中请求权限

在应用注册门户中，应用程序可以列出其所需的权限，包括委托的权限和应用程序权限。 此设置允许使用 .default 范围和 Microsoft Entra 管理门户的“授予管理员同意”选项。

通常，这些权限应该是为给定的应用程序静态定义的。 它们应该是应用程序会以动态或增量方式请求的权限的超集。

注意

只能通过使用 .default 来请求应用程序权限。 因此，如果应用程序需要应用程序权限，请确保这些权限在应用注册门户中列出。

配置应用程序的静态请求权限列表：

  1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
  2. 浏览到“标识”>“应用程序”>“应用注册”>“所有应用程序”。
  3. 选择一个应用程序，或创建一个应用（如尚未创建）。
  4. 在应用程序的“概述”页的“管理”下，选择“API 权限”>“添加权限”。
  5. 从可用 API 的列表中选择“Microsoft Graph”。 然后添加应用所需的权限。
  6. 选择“添加权限”。

成功的响应

如果管理员批准了应用的权限，成功响应如下所示：

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
参数 说明
tenant 向应用程序授予所请求权限的目录租户（采用 GUID 格式）。
state 同样随令牌响应返回的请求中所包含的值。 可以是所需的任何内容的字符串。 该状态用于对发出身份验证请求出现之前，有关用户在应用程序中的状态的信息（例如前面所在的页面或视图）编码。
admin_consent 将设置为 True。

从管理员同意终结点收到成功响应后，应用程序便已获得所请求的权限。 接下来，可以请求所需的资源令牌。

错误响应

如果管理员未批准应用的权限，失败响应将如下所示：

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
参数 说明
error 错误代码字符串，可用于对发生的错误类型进行分类。 它还可用于对错误做出响应。
error_description 可帮助开发人员识别错误根本原因的具体错误消息。

用户同意应用的权限之后，应用程序即可获取访问令牌，这些令牌表示应用以某种身份访问资源的权限。 访问令牌只能用于单个资源， 但其内部编码了应用程序已被授予的该资源的每一项权限。 若要获取访问令牌，应用程序可以对 Microsoft 标识平台令牌终结点发出类似于以下请求：

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": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

可在资源的 HTTP 请求中使用生成的访问令牌。 该令牌以可靠方式向资源表明，应用程序已获得适当权限，可执行特定的任务。

有关 OAuth 2.0 协议以及如何获取访问令牌的详细信息，请参阅 Microsoft 标识平台终结点协议参考。

另请参阅