通过

自定义令牌

  • 项目

本文帮助你使用 Microsoft 标识平台的 ID 令牌、访问令牌和安全令牌将安全性构建到应用程序中。 其中介绍了可以在 Microsoft Entra 令牌中接收的信息，以及如何自定义它们。 这是关于独立软件开发人员 (ISV) 如何为 Microsoft Entra ID 生成和优化其应用程序的系列文章中的第五篇文章。 在此系列中，可以了解有关以下主题的详细信息：

连接到 Microsoft Entra ID 的应用程序的主要操作是请求和处理令牌。 作为开发人员，你可以自定义 Microsoft Entra ID 发送到委托的权限应用或 API 的令牌。 你不能自定义工作负载令牌。

如果应用程序实现 OpenID Connect (OIDC) 并请求 ID 令牌，则可以自定义应用的 ID 令牌。 如果实现 API，则可以自定义调用 API 的应用接收的访问令牌。 应用程序无法自定义它收到的用于授权应用访问 API 的访问令牌。

ISV 的主要令牌自定义方法是将可选声明添加到应用注册中的令牌。 可选声明参考列出了可用的可选声明。

对于多租户应用，可选声明可供每个租户使用。 可以将 API 访问令牌配置为包含可选的 onprem_sid 声明，以包含用户的本地安全标识声明。 虽然可以配置可选声明，但应用程序必须始终处理令牌不包含配置的可选声明的情况。 例如，用户可以是没有本地安全标识符的仅 Microsoft Entra ID 用户。 在这种情况下，Microsoft Entra ID 不包括令牌中的可选声明。 Microsoft Entra ID 不返回空值 ("") 的声明。

组声明是需要特殊处理的可选声明。 应用或 API 可以包含令牌中的用户安全组和嵌套组，或者包含具有组声明的通讯组列表的安全组和嵌套组。 应用程序可以使用 wids（租户范围角色）声明将用户的目录角色包含在令牌中。 包括所有用户的组和/或通讯组列表可能导致令牌中没有组或通讯组列表。

令牌大小限制组声明中的总条目数，OAuth 2.0 应用为 200 个，SAML 应用为 150 个，使用隐式授权作为混合流一部分的应用为 6 个。 当组过多时，令牌具有组超额声明。 如果令牌包含组超额声明，请返回到调用 Microsoft Graph 以获取用户的组。 由于你无法知道用户何时是过多组的成员，因此请始终在应用中包含调用 Microsoft Graph 来获取用户组成员身份的功能。 由于 Microsoft Graph 代码要求，建议使用 Microsoft Graph 而不使用组声明。

为了避免组超额，请将组声明配置为仅包括应用程序向其分配的组。 使用此方法时，组声明仅包括当用户是组成员时分配给应用或 API 的组（不支持嵌套组）。 用户必须是应用分配的组的直接成员。

避免组超额的另一种方法是使用角色而不是组。 可以为令牌中收到的应用程序或 API 配置角色。 IT 管理员可以将组分配给你在具有 P1 或更高版本许可的 Microsoft Entra ID 租户中定义的角色。 分配后，令牌包含具有用户分配角色的应用的角色声明，或基于用户的组成员身份的角色。

评估使用组或角色的权衡。 对于 ISV，建议使用角色而不是组。

后续步骤