使用 Microsoft Entra ID 为应用程序配置组声明

项目
12/19/2024

Microsoft Entra ID 可以在令牌中提供用户的组成员身份信息（可在应用程序内使用）。此功能支持三种主要模式：

由组的 Microsoft Entra 对象标识符 (OID) 特性标识的组
按 Active Directory 同步组和用户的 sAMAccountName 或 GroupSID 特性标识的组
由仅限云的组的显示名称属性标识的组

重要

对于 SAML 断言和 JWT，令牌中发出的组数分别被限制为 150 个和 200 个，包括嵌套组。在规模较大的组织中，用户所加入的组的数量可能会超过 Microsoft Entra ID 在令牌中发出组声明之前所应用的限制。超过此限制将导致 Microsoft Entra ID 完全省略在令牌中发送组声明。有关这些限制的解决方法，请参阅此功能的重要注意事项。

此功能的重要注意事项

支持使用从本地同步的 sAMAccountName 和安全标识符 (SID) 特性的目的是为了能够从 Active Directory 联合身份验证服务 (AD FS) 和其他标识提供者移动现有应用程序。在 Microsoft Entra ID 中管理的组不包含发出这些声明所需的特性。
如果用户具有大量组成员身份，为了避免组数限制，可以将声明中发出的组限制为应用程序的相关组。详细了解如何为 JWT 令牌和 SAML 令牌发出分配给应用程序的组。如果无法将组分配到应用程序，还可以配置组筛选器以减少在声明中发出的组数。组筛选适用于为在门户的“企业应用”边栏选项卡中配置组声明和筛选的应用发出的令牌。请记住，在规模较大的组织中，用户所加入的组的数量可能会超过 Microsoft Entra ID 在令牌中发出组声明之前所应用的限制。超过此限制将导致 Microsoft Entra ID 完全省略在令牌中发送组声明。
如果令牌是通过隐式流颁发的，则组声明具有 5 组限制。仅当用户在 5 个以上的组中时，通过隐式流请求的令牌才有 "hasgroups":true 声明。
对于以下情况，我们建议使应用内角色基于应用程序角色，而不是基于组：
- 对于正在开发的新应用程序或现有应用程序都可以使用这种配置。
- 不需要嵌套组支持。
使用应用程序角色可以限制需要传入令牌的信息量，且更安全，而且还能将用户分配与应用配置分隔开来。

从 AD FS 和其他标识提供者迁移的应用程序的组声明

许多已配置为使用 AD FS 进行身份验证的应用程序依赖于 Windows Server Active Directory 组特性形式的组成员身份信息。这些特性是可按域名限定的组 sAMAccountName，或者是 Windows 组安全标识符 (GroupSID)。当应用程序与 AD FS 联合时，AD FS 将使用 TokenGroups 函数来检索用户的组成员身份。

已从 AD FS 移动的应用需要相同格式的声明。从 Microsoft Entra ID 发出的组和角色声明可能包含域限定的 sAMAccountName 特性或从 Active Directory 同步的 GroupSID 特性，而不是组的 Microsoft Entra ID objectID 特性。

组声明支持的格式为：

Microsoft Entra 组 ObjectId：可用于所有组。
sAMAccountName：可用于从 Active Directory 同步的组。
NetbiosDomain\sAMAccountName：可用于从 Active Directory 同步的组。
DNSDomainName\sAMAccountName：可用于从 Active Directory 同步的组。
本地组安全标识符：可用于从 Active Directory 同步的组。

注意

sAMAccountName 和本地 GroupSID 特性仅可用于从 Active Directory 同步的组对象。它们不可用于在 Microsoft Entra ID 或 Office 365 中创建的组。在 Microsoft Entra ID 中配置为获取已同步本地组特性的应用程序只会获取已同步组的这些特性。

供应用程序使用组信息的选项

应用程序可以调用 Microsoft Graph 组终结点来获取经过身份验证的用户的组信息。此调用确保即使涉及到大量的组，某个用户所属的所有组也仍可供使用。然后，组枚举可以不考虑令牌大小限制。

但是，如果现有应用程序预期通过声明使用组信息，你可以在 Microsoft Entra ID 中配置各种声明格式。请考虑以下选项：

将组成员身份用于应用程序内授权时，最好是使用组 ObjectID 特性。组 ObjectID 特性在 Microsoft Entra ID 中是不可变且唯一的。它可用于所有组。
如果使用本地组 sAMAccountName 特性进行授权，请使用域限定的名称。这样可以减少名称冲突的可能性。 sAMAccountName 在 Active Directory 域中可能是唯一的，但如果有多个 Active Directory 域已与某个 Microsoft Entra 租户同步，则可能会出现多个组同名的情况。
请考虑使用应用程序角色在组成员身份与应用程序之间提供一个间接层。然后，应用程序会根据令牌中的角色声明做出内部授权决策。
如果将应用程序配置为获取已从 Active Directory 同步的组特性，而某个组并不包含这些特性，则不会将该组包含在声明中。
令牌中的组声明包括嵌套组，但使用相应选项将组声明限制为已分配给应用程序的组时除外。

如果某个用户是组 B 的成员，而组 B 是组 A 的成员，则该用户的组声明将包含组 A 和组 B。当组织中的用户是大量组的成员时，令牌中列出的组数可能会增大令牌大小。对于 SAML 断言和 JWT，Microsoft Entra ID 将它在令牌中发出的组数分别限制为 150 个和 200 个。如果某个用户是更多组的成员，则会忽略这些组。将改为包含用于获取组信息的 Microsoft Graph 终结点的链接。

使用从 Active Directory 同步的组特性的先决条件

如果使用 ObjectId 格式，可以在任何组的令牌中发出组成员身份声明。若要使用除组 ObjectId 以外的格式的组声明，必须通过 Microsoft Entra Connect 从 Active Directory 同步组。

若要将 Microsoft Entra ID 配置为发出 Active Directory 组的组名，请执行以下操作：

从 Active Directory 同步组名

在 Microsoft Entra ID 可以在组或角色声明中发出组名或本地组 SID 之前，你需要从 Active Directory 同步所需的特性。必须运行 Microsoft Entra Connect 1.2.70 或更高版本。低于 1.2.70 的 Microsoft Entra Connect 版本将从 Active Directory 同步组对象，但不会包含所需的组名特性。
将 Microsoft Entra ID 中的应用程序注册配置为在令牌中包含组声明

可以在门户的“企业应用程序”部分或者使用“应用程序注册”部分的应用程序清单来配置组声明。若要在应用程序清单中配置组声明，请参阅本文稍后的在 Microsoft Entra 应用程序注册中配置组特性。

使用 SSO 配置将组声明添加到 SAML 应用程序的令牌

若要通过单一登录 (SSO) 为库或非库 SAML 应用程序配置组声明，请执行以下操作：

打开“企业应用程序”，在列表中单击该应用程序，选择“单一登录配置”，然后选择“用户特性和声明”。
选择“添加组声明”。

使用相应的选项选择要将哪些组包含在令牌中。

显示具有组选项的“组声明”窗口的屏幕截图。

选择	说明
所有组	发出安全组、通讯组列表和角色。
安全组	在组声明中发出用户所属的安全组。如果为用户分配了目录角色，这些角色将作为对象 ID 发出。
目录角色	如果为用户分配了目录角色，这些角色将作为 `wids` 声明发出。（不会发出组的声明。）
分配给应用程序的组	仅发出已显式分配给应用程序并且用户所属的组。由于令牌中的组数限制，建议用于大型组织。

例如，若要发出用户所属的所有安全组，请选择“安全组”。

若要使用已从 Active Directory 同步的 Active Directory 特性（而不是 Microsoft Entra ID objectID 特性）发出组，请从“源特性”下拉列表中选择所需的格式。声明中只会包含已从 Active Directory 同步的组。
若要仅发出已分配给应用程序的组，请选择“分配给应用程序的组”。

令牌中将包含已分配给应用程序的组。将忽略用户所属的其他组。使用此选项时，将不包含嵌套组，并且用户必须是已分配给应用程序的组的直属成员。

若要更改分配给应用程序的组，请在“企业应用程序”列表中选择该应用程序。然后在该应用程序的左侧菜单中选择“用户和组”。

有关管理应用程序的组分配的详细信息，请参阅文档将用户或组分配到企业应用。

在令牌中发出仅限云的组显示名称

可以将组声明配置为包含仅限云的组的组显示名称。

打开“企业应用程序”，在列表中单击该应用程序，选择“单一登录配置”，然后选择“用户特性和声明”。
如果已配置组声明，请从“其他声明”部分选择它。否则，可以按照前面步骤中所述添加组声明。
对于令牌中发出的组类型，请选择“分配给应用程序的组”：
若要仅针对云组发出组显示名称，请在“源属性”下拉列表中选择“仅限云的组显示名称”：
对于混合设置，若要发出同步组的本地组属性和云组的显示名称，可以选择所需的本地源属性，并选中“发出仅限云组的组名称”复选框：

注意

只能将已分配组的云组名称添加到应用程序。对 groups assigned to the application 进行限制是因为组名称不唯一，并且只能为显式分配给应用程序的组发出显示名称，以降低安全风险。否则，任何用户都可以创建具有重复名称的组，并在应用程序端获取访问权限。

设置高级选项

自定义组声明名称

可以使用“高级选项”下的设置修改组声明的发出方式。

如果选择“自定义组声明的名称”，则可为组声明指定不同的声明类型。在“名称”框中输入声明类型，并在“命名空间”框中输入声明的可选命名空间。

显示“高级选项”的屏幕截图，其中选择了“自定义组声明的名称”，并输入了“名称”和“命名空间”值。

某些应用程序要求在角色声明中显示组成员身份信息。可以选择性地选中“将组作为角色声明发出”复选框，以将用户的组作为角色发出。

显示高级选项的屏幕截图，其中选中了“自定义组声明的名称”和“将组作为角色声明发出”复选框。

注意

如果使用将组数据作为角色发出的选项，则角色声明中只会显示组。分配给用户的任何应用程序角色都不会显示在角色声明中。

组筛选

组筛选允许对包含在组声明中的组列表进行精细控制。配置筛选器后，只有与筛选器匹配的组才会包含在发送到该应用程序的组声明中。筛选滤器都将应用于所有组，无论组层次结构如何。

注意

组筛选适用于为在门户的“企业应用”边栏选项卡中配置组声明和筛选的应用发出的令牌。
组筛选不适用于 Microsoft Entra 角色。

可以配置应用于组的显示名称或 SAMAccountName 特性的筛选器。支持以下筛选操作：

前缀：匹配所选特性的开头。
后缀：匹配所选特性的结尾。
包含：匹配所选特性中的任何位置。

显示筛选选项的屏幕截图。

组变换

某些应用程序所需的组格式不同于它们在 Microsoft Entra ID 中的表示格式。为了支持此要求，可以对将在组声明中发出的每个组应用转换。为此，可以在自定义组声明中配置正则表达式 (regex) 和替换值。

组转换的屏幕截图，其中添加了正则表达式信息。 \

正则表达式模式：使用正则表达式根据在此框中设置的模式来分析文本字符串。如果概述的正则表达式模式计算为 true，则将运行正则表达式替换模式。
正则表达式替换模式：以正则表达式表示法概述当所概述的正则表达式模式计算为 true 时，要如何替换字符串。使用捕获组匹配此替换正则表达式中的子表达式。

有关正则表达式替换和捕获组的详细信息，请参阅正则表达式对象模型：捕获的组。

注意

如 Microsoft Entra 文档中所述，不能使用策略来修改受限声明。无法更改数据源，并且在生成这些声明时不应用任何转换。组声明仍然是受限声明，因此你需要通过更改名称来自定义组。如果选择一个受限名称作为自定义组声明的名称，在运行时将忽略该声明。

还可以将正则表达式转换功能用作筛选器，因为不符合正则表达式模式的任何组都不会在生成的声明中发出。

如果应用于原始组声明的转换会产生新的自定义声明，则原始组声明将从令牌中省略。但是，如果配置的正则表达式与原始列表中的任何值都不匹配，则自定义声明将不存在，并且原始组声明将包含在令牌中。

编辑组声明配置

将组声明配置添加到“用户属性和声明”配置后，用于添加组声明的选项将不可用。若要更改组声明配置，请在“其他声明”列表中选择该组声明。

用于用户属性和声明的区域的屏幕截图，其中突出显示了组声明名称。

在 Microsoft Entra 应用程序注册中配置组特性

还可以在应用程序清单的可选声明部分配置组声明。

在门户中，选择“标识”>“应用程序”>“应用注册”>“选择应用程序”>“清单”。

通过更改 groupMembershipClaims 来启用组成员身份声明。

有效值为：

选择	说明
`All`	发出安全组、通讯组列表和角色。
`SecurityGroup`	在组声明中发出用户所属的安全组和 Microsoft Entra 角色。
`DirectoryRole`	如果为用户分配了目录角色，这些角色将作为 `wids` 声明发出。（不会发出组声明。）
`ApplicationGroup`	仅发出已显式分配给应用程序并且用户所属的组。
`None`	不返回任何组。（此值不区分大小写，因此也可以指定 `none`。可以直接在应用程序清单中设置。）

例如：

"groupMembershipClaims": "SecurityGroup"

默认情况下，将在组声明值中发出组 ObjectID 特性。若要修改声明值以包含本地组属性，或者要将声明类型更改为角色，请按下一步骤中所述使用 optionalClaims 配置。

为组名配置设置可选声明。

如果你希望令牌中的组包含本地 Active Directory 组特性，请在 optionalClaims 部分指定要将可选声明应用到哪个令牌类型。可以列出多种令牌类型：

idToken 表示 OIDC ID 令牌
accessToken 表示 OAuth /OIDC 访问令牌
Saml2Token 表示 SAML 令牌

注意

Saml2Token 类型适用于 SAML1.1 和 SAML2.0 格式的令牌。

对于每个相关的令牌类型，请修改组声明以使用清单中的 optionalClaims 部分。 optionalClaims 架构如下所述：

{
"name": "groups",
"source": null,
"essential": false,
"additionalProperties": []
}

可选声明架构	值
`name`	必须是 `"groups"`。
`source`	未使用。省略或指定 `null`。
`essential`	未使用。省略或指定 `false`。
`additionalProperties`	附加属性列表。有效选项为 `"sam_account_name"`、`"dns_domain_and_sam_account_name"`、`"netbios_domain_and_sam_account_name"`、`"cloud_displayname"` 和 `"emit_as_roles"`。

在 additionalProperties 中，只需 "sam_account_name"、"dns_domain_and_sam_account_name" 和 "netbios_domain_and_sam_account_name" 中的一个。如果存在多个选项，则将使用第一个选项并忽略其他选项。

某些应用程序需要角色声明中有关用户的组信息。若要将声明类型从组声明更改为角色声明，请将 "emit_as_roles" 添加到附加属性。组值将在角色声明中发出。

若要发出仅限云组的组显示名称，可以将 "cloud_displayname" 添加到 additional properties。仅当 “groupMembershipClaims” 设置为 ApplicationGroup 时，此选项才有效

注意

如果使用 "emit_as_roles"，则分配给用户的任何已配置应用程序角色不会显示在角色声明中。

示例

在 OAuth 访问令牌中以 DNSDomainName\sAMAccountName 格式将组作为组名发出：

"optionalClaims": {
    "accessToken": [{
        "name": "groups",
        "additionalProperties": ["dns_domain_and_sam_account_name"]
    }]
}

在 SAML 和 OIDC ID 令牌中以 NetbiosDomain\sAMAccountName 格式将要返回的组名作为角色声明发出：

"optionalClaims": {
    "saml2Token": [{
        "name": "groups",
        "additionalProperties": ["netbios_domain_and_sam_account_name", "emit_as_roles"]
    }],

    "idToken": [{
        "name": "groups",
        "additionalProperties": ["netbios_domain_and_sam_account_name", "emit_as_roles"]
    }]
}

通过