Microsoft 标识平台中的管理员同意
某些权限需要获得管理员同意才能在租户中授予。 你还可以使用管理员许可终结点向整个租户授予权限。
建议:让用户登录到应用
在构建使用管理员许可终结点的应用程序时,应用通常需要一个页面或视图,使管理员能够批准应用的权限。 此页面可以是应用注册流的一部分、应用设置的一部分,或者专用的“连接”流。 在许多情况下,合理的结果是只有在用户使用工作或学校帐户登录后,应用才显示此“连接”视图。
将用户登录到应用后,便可识别管理员所属的组织,然后要求他们批准必要的权限。 尽管在严格意义上不需要这样做,但这有助于为组织用户带来更直观的体验。
向目录管理员请求权限
准备好向组织管理员请求权限时,可将用户重定向到 Microsoft 标识平台管理员许可终结点。
https://login.partner.microsoftonline.cn/{tenant}/v2.0/adminconsent
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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 范围(openid 、profile 、email )。 |
此时,Microsoft Entra ID 会要求租户管理员进行登录来完成请求。 系统要求管理员批准你在 scope
参数中请求的所有权限。 如果你使用了静态 (/.default
) 值,则它运行起来将类似于 v1.0 管理员同意终结点,并会请求对所需权限(用户所需权限和应用所需权限)中找到的所有范围的同意。 若要请求应用权限,必须使用 /.default
值。 如果你不希望管理员在你使用 /.default
时始终在管理员同意屏幕中看到给定的权限,则最佳做法是不要将权限置于“所需权限”部分。 你可以改为在运行时使用动态同意将想要的权限添加到同意屏幕,而不是使用 /.default
。
成功的响应
如果管理员批准了应用的权限,成功响应如下所示:
http://localhost/myapp/permissions
?admin_consent=True
&tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee
&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+0000aaaa-11bb-cccc-dd22-eeeeee333333%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 ,以指示此响应发生在管理员同意流上。 |
后续步骤
- 请参阅如何将应用转换为多租户应用
- 了解如何在授权代码授予流期间在 OAuth 2.0 协议层提供许可支持。
- 了解多租户应用程序如何使用许可框架来实现“用户”许可和“管理员”许可,为更高级的多层应用程序模式提供支持。
- 了解 Microsoft Entra 应用程序同意体验