通过

通过同意请求权限

  • 项目

Microsoft标识平台中的应用程序依赖于同意，以获取对必要资源或 API 的访问权限。 对于不同的应用程序方案，不同类型的同意效果更好。 选择应用程序获取用户同意的最佳方法将有助于用户和组织更有效地使用该应用程序。

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

在静态用户同意方案中，必须在Microsoft Entra 管理中心的应用配置中指定它所需的所有权限。 如果用户（或管理员）未为此应用授予许可，则Microsoft标识平台将提示用户此时提供同意。

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

虽然依赖静态同意和单个权限列表使代码保持良好且简单，但也意味着你的应用将请求它可能事先需要的所有权限。 这可以阻止用户和管理员批准应用的访问权限请求。

使用Microsoft标识平台终结点，可以忽略 Microsoft Entra 管理中心的应用程序注册信息中定义的静态权限。 相反，你可以以增量方式请求权限。 可以提前请求最少的权限集，并随着客户使用其他应用程序功能而请求更多权限。 为此，你可以通过在请求访问令牌时在参数中包含scope新范围来指定应用程序需要的范围-而无需在应用程序注册信息中预先定义它们。 如果用户尚未许可添加到请求的新范围，则系统会提示他们仅许可新的权限。 增量许可或动态许可仅适用于委派权限，不适用于应用程序权限。

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

重要

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

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

GET https://login.microsoftonline.com/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%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%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图形权限的完整列表，请参阅 Microsoft图形权限参考。

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

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

注释

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

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

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

管理员可以使用以下选项为应用程序授予许可。

通常，在生成需要管理员同意的应用程序时，应用程序需要页面或视图，管理员可以在其中批准应用的权限。 此页面可以是：

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

在许多情况下，只有在用户使用工作Microsoft帐户或学校Microsoft帐户登录后，应用程序才会显示“连接”视图。

将用户登录到应用时，可以先确定管理员所属的组织，然后要求他们批准必要的权限。 尽管此步骤并非严格必要，但它可以帮助你为组织用户创建更直观的体验。

要登录用户，请按照 Microsoft 身份验证平台协议教程操作。

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

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

一般情况下，应为给定应用程序静态定义权限。 它们应该是应用程序将动态或增量请求的权限的超集。

注释

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

若要为应用程序配置静态请求的权限列表，请执行以下作：

  1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
  2. 导航到 Entra ID>应用注册>所有应用程序。
  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
参数 DESCRIPTION
tenant 授予您的应用程序其请求权限的目录租户，其格式为 GUID。
state 请求中包含的一个值，该值也将在令牌响应中返回。 可以是所需的任何内容的字符串。 该状态用于在身份验证请求发生之前对应用程序中用户状态的信息进行编码，例如他们打开的页面或视图。
admin_consent 将设置为 True.

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

错误响应

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

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

用户同意应用的权限后，应用程序可以获取访问令牌，这些令牌表示应用在某些容量中访问资源的权限。 访问令牌只能用于单个资源。 但是，访问令牌中编码了应用程序已被授予用于该资源的所有权限。 若要获取访问令牌，应用程序可以向Microsoft标识平台令牌终结点发出请求，如下所示：

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
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标识平台终结点协议参考。

另请参阅