Microsoft 标识平台中的管理员同意

某些权限需要获得管理员同意才能在租户中授予。 你还可以使用管理员许可终结点向整个租户授予权限。

在构建使用管理员许可终结点的应用程序时,应用通常需要一个页面或视图,使管理员能够批准应用的权限。 此页面可以是应用注册流的一部分、应用设置的一部分,或者专用的“连接”流。 在许多情况下,合理的结果是只有在用户使用工作或学校帐户登录后,应用才显示此“连接”视图。

将用户登录到应用后,便可识别管理员所属的组织,然后要求他们批准必要的权限。 尽管在严格意义上不需要这样做,但这有助于为组织用户带来更直观的体验。

向目录管理员请求权限

准备好向组织管理员请求权限时,可将用户重定向到 Microsoft 标识平台管理员许可终结点

https://login.partner.microsoftonline.cn/{tenant}/v2.0/adminconsent
        ?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
        &scope=https://microsoftgraph.chinacloudapi.cn/Calendars.Read https://microsoftgraph.chinacloudapi.cn/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
参数 条件 描述
tenant 必需 要向其请求权限的目录租户。 可以采用 GUID 或友好名称格式提供或使用 organizations 以一般方式引用,如示例所示。
client_id 必须 Microsoft Entra 管理中心 - 应用注册体验分配给应用的应用程序(客户端)ID
redirect_uri 必须 要向其发送响应,供应用处理的重定向 URI。 必须与在应用注册门户中注册的重定向 URI 之一完全匹配。
state 建议 同样随令牌响应返回的请求中所包含的值。 可以是所需的任何内容的字符串。 使用该状态可在身份验证请求出现之前,在应用中编码用户的状态信息,例如用户过去所在的页面或视图。
scope 必需 定义应用程序请求的权限集。 这可以是静态范围(使用 /.default)或动态范围。 这可以包括 OIDC 范围(openidprofileemail)。

此时,Microsoft Entra ID 会要求租户管理员进行登录来完成请求。 系统要求管理员批准你在 scope 参数中请求的所有权限。 如果你使用了静态 (/.default) 值,则它运行起来将类似于 v1.0 管理员同意终结点,并会请求对所需权限(用户所需权限和应用所需权限)中找到的所有范围的同意。 若要请求应用权限,必须使用 /.default 值。 如果你不希望管理员在你使用 /.default 时始终在管理员同意屏幕中看到给定的权限,则最佳做法是不要将权限置于“所需权限”部分。 你可以改为在运行时使用动态同意将想要的权限添加到同意屏幕,而不是使用 /.default

成功的响应

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

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=fa00d692-e9c7-4460-a743-29f2956fd429
    &scope=https://microsoftgraph.chinacloudapi.cn/Calendars.Read https://microsoftgraph.chinacloudapi.cn/Mail.Send
    &state=12345
参数 说明
tenant 向应用程序授予所请求权限的目录租户(采用 GUID 格式)。
state 同样随令牌响应返回的请求中所包含的值。 可以是所需的任何内容的字符串。 该 state 用于在身份验证请求出现之前,于应用中编码用户的状态信息,例如之前所在的页面或视图。
scope 为应用程序授予访问权限的权限集。
admin_consent 将设置为 True

警告

切勿使用 tenant 参数的租户 ID 值对用户进行身份验证或授权。 不良行动者可以更新和发送租户 ID 值,模拟对应用的响应。 这可能会导致应用程序面临安全事件。

错误响应

http://localhost/myapp/permissions
        ?admin_consent=True
        &error=consent_required
        &error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+d320620c-3d56-42bc-bc45-4cdd85c41f00%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

除了在成功响应中看到的参数外,错误参数如下所示。

参数 说明
error 可用于分类发生的错误类型与响应错误的错误码字符串。
error_description 可帮助开发人员识别错误根本原因的具体错误消息。
state 同样随令牌响应返回的请求中所包含的值。 可以是所需的任何内容的字符串。 该 state 用于在身份验证请求出现之前,于应用中编码用户的状态信息,例如之前所在的页面或视图。
admin_consent 将设置为 True,以指示此响应发生在管理员同意流上。

后续步骤