Configure group claims for applications by using Microsoft Entra ID
Microsoft Entra ID can provide a user's group membership information in tokens for use within applications. This feature supports three main patterns:
- Groups identified by their Microsoft Entra object identifier (OID) attribute
- Groups identified by the
sAMAccountName
orGroupSID
attribute for Active Directory-synchronized groups and users - Groups identified by their Display Name attribute for cloud-only groups
Important
The number of groups emitted in a token is limited to 150 for SAML assertions and 200 for JWT, including nested groups. In larger organizations, the number of groups where a user is a member might exceed the limit that Microsoft Entra ID applies before emitting groups claims in a token. Exceeding this limit will cause Microsoft Entra ID completely omit sending group claims in the token. For workarounds to these limits, read more in Important caveats for this functionality.
Support for use of
sAMAccountName
and security identifier (SID) attributes synced from on-premises is designed to enable moving existing applications from Active Directory Federation Services (AD FS) and other identity providers. Groups managed in Microsoft Entra ID don't contain the attributes necessary to emit these claims.In order to avoid the number of groups limit if your users have large numbers of group memberships, you can restrict the groups emitted in claims to the relevant groups for the application. Read more about emitting groups assigned to the application for JWT tokens and SAML tokens. If assigning groups to your applications is not possible, you can also configure a group filter to reduce the number of groups emitted in the claim. Group filtering applies to tokens emitted for apps where group claims and filtering were configured in the Enterprise apps blade in the portal. Keep in mind that in larger organizations, the number of groups where a user is a member might exceed the limit that Microsoft Entra ID applies before emitting groups claims in a token. Exceeding this limit will cause Microsoft Entra ID completely omit sending group claims in the token.
Group claims have a five-group limit if the token is issued through the implicit flow. Tokens requested via the implicit flow will have a
"hasgroups":true
claim only if the user is in more than five groups.We recommend basing in-app authorization on application roles rather than groups when:
- You're developing a new application, or an existing application can be configured for it.
- Support for nested groups isn't required.
Using application roles limits the amount of information that needs to go into the token, is more secure, and separates user assignment from app configuration.
Many applications that are configured to authenticate with AD FS rely on group membership information in the form of Windows Server Active Directory group attributes. These attributes are the group sAMAccountName
, which might be qualified by domain name, or the Windows group security identifier (GroupSID
). When the application is federated with AD FS, AD FS uses the TokenGroups
function to retrieve the group memberships for the user.
An app that has been moved from AD FS needs claims in the same format. Group and role claims emitted from Microsoft Entra ID might contain the domain-qualified sAMAccountName
attribute or the GroupSID
attribute synced from Active Directory, rather than the group's Microsoft Entra ID objectID
attribute.
The supported formats for group claims are:
- Microsoft Entra group ObjectId: Available for all groups.
- sAMAccountName: Available for groups synchronized from Active Directory.
- NetbiosDomain\sAMAccountName: Available for groups synchronized from Active Directory.
- DNSDomainName\sAMAccountName: Available for groups synchronized from Active Directory.
- On-premises group security identifier: Available for groups synchronized from Active Directory.
Note
sAMAccountName
and on-premises GroupSID
attributes are available only on group objects synced from Active Directory. They aren't available on groups created in Microsoft Entra ID or Office 365. Applications configured in Microsoft Entra ID to get synced on-premises group attributes get them for synced groups only.
Applications can call the Microsoft Graph group's endpoint to obtain group information for the authenticated user. This call ensures that all the groups where a user is a member are available, even when a large number of groups is involved. Group enumeration is then independent of limitations on token size.
However, if an existing application expects to consume group information via claims, you can configure Microsoft Entra ID with various claim formats. Consider the following options:
When you're using group membership for in-application authorization, it's preferable to use the group
ObjectID
attribute. The groupObjectID
attribute is immutable and unique in Microsoft Entra ID. It's available for all groups.If you're using the on-premises group
sAMAccountName
attribute for authorization, use domain-qualified names. It reduces the chance of names clashing.sAMAccountName
might be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with a Microsoft Entra tenant, there's a possibility for more than one group to have the same name.Consider using application roles to provide a layer of indirection between the group membership and the application. The application then makes internal authorization decisions based on role claims in the token.
If the application is configured to get group attributes that are synced from Active Directory and a group doesn't contain those attributes, it won't be included in the claims.
Group claims in tokens include nested groups, except when you're using the option to restrict the group claims to groups that are assigned to the application.
If a user is a member of GroupB, and GroupB is a member of GroupA, then the group claims for the user will contain both GroupA and GroupB. When an organization's users have large numbers of group memberships, the number of groups listed in the token can grow the token size. Microsoft Entra ID limits the number of groups that it will emit in a token to 150 for SAML assertions and 200 for JWT. If a user is a member of a larger number of groups, the groups are omitted. A link to the Microsoft Graph endpoint to obtain group information is included instead.
Group membership claims can be emitted in tokens for any group if you use the ObjectId
format. To use group claims in formats other than group ObjectId
, the groups must be synchronized from Active Directory via Microsoft Entra Connect.
To configure Microsoft Entra ID to emit group names for Active Directory groups:
Synchronize group names from Active Directory
Before Microsoft Entra ID can emit the group names or on-premises group SID in group or role claims, you need to synchronize the required attributes from Active Directory. You must be running Microsoft Entra Connect version 1.2.70 or later. Earlier versions of Microsoft Entra Connect than 1.2.70 will synchronize the group objects from Active Directory, but they won't include the required group name attributes.
Configure the application registration in Microsoft Entra ID to include group claims in tokens
You can configure group claims in the Enterprise Applications section of the portal, or by using the application manifest in the Application Registrations section. To configure group claims in the application manifest, see Configure the Microsoft Entra application registration for group attributes later in this article.
To configure group claims for a gallery or non-gallery SAML application via single sign-on (SSO):
Open Enterprise Applications, select the application in the list, select Single Sign On configuration, and then select User Attributes & Claims.
Select Add a group claim.
Use the options to select which groups should be included in the token.
Selection Description All groups Emits security groups and distribution lists and roles. Security groups Emits security groups that the user is a member of in the groups claim. If the user is assigned directory roles, they're emitted as object ID. Directory roles If the user is assigned directory roles, they're emitted as a wids
claim. (The group's claim won't be emitted.)Groups assigned to the application Emits only the groups that are explicitly assigned to the application and that the user is a member of. Recommended for large organizations due to the group number limit in token. For example, to emit all the security groups that the user is a member of, select Security groups.
To emit groups by using Active Directory attributes synced from Active Directory instead of Microsoft Entra ID
objectID
attributes, select the required format from the Source attribute drop-down list. Only groups synchronized from Active Directory will be included in the claims.To emit only groups assigned to the application, select Groups assigned to the application.
Groups assigned to the application will be included in the token. Other groups that the user is a member of will be omitted. With this option, nested groups are not included and the user must be a direct member of the group assigned to the application.
To change the groups assigned to the application, select the application from the Enterprise Applications list. Then select Users and Groups from the application's left menu.
For more information about managing group assignment to applications, see Assign a user or group to an enterprise app.
You can configure group claim to include the group display name for the cloud-only groups.
Open Enterprise Applications, select the application in the list, select Single Sign On configuration, and then select User Attributes & Claims.
If you already have group claims configured, select it from the Additional claims section. Otherwise, you can add the group claim as described in the previous steps.
For the group type emitted in the token select Groups assigned to the application:
To emit group display name just for cloud groups, in the Source attribute dropdown select the Cloud-only group display names:
For a hybrid setup, to emit on-premises group attribute for synced groups and display name for cloud groups, you can select the desired on-premises sources attribute and check the checkbox Emit group name for cloud-only groups:
Note
You can only add cloud-group names of assigned groups to an application. The restriction to groups assigned to the application
is because a group name is not unique, and display names can only be emitted for groups explicitly assigned to the application to reduce the security risks. Otherwise, any user could create a group with duplicate name and gain access in the application side.
You can modify the way that group claims are emitted by using the settings under Advanced options.
If you select Customize the name of the group claim, you can specify a different claim type for group claims. Enter the claim type in the Name box and the optional namespace for the claim in the Namespace box.
Some applications require the group membership information to appear in the role claim. You can optionally emit the user's groups as roles by selecting the Emit groups as role claims checkbox.
Note
If you use the option to emit group data as roles, only groups will appear in the role claim. Any application roles that the user is assigned to won't appear in the role claim.
Group filtering allows for fine control of the list of groups that's included as part of the group claim. When a filter is configured, only groups that match the filter will be included in the group's claim that's sent to that application. The filter will be applied against all groups regardless of the group hierarchy.
Note
Group filtering applies to tokens emitted for apps where group claims and filtering was configured in the Enterprise apps blade in the portal.
Group filtering does not apply to Microsoft Entra roles.
You can configure filters to be applied to the group's display name or SAMAccountName
attribute. The following filtering operations are supported:
- Prefix: Matches the start of the selected attribute.
- Suffix: Matches the end of the selected attribute.
- Contains: Matches any location in the selected attribute.
Some applications might require the groups in a different format from how they're represented in Microsoft Entra ID. To support this requirement, you can apply a transformation to each group that will be emitted in the group claim. You achieve it by allowing the configuration of a regular expression (regex) and a replacement value on custom group claims.
\
- Regex pattern: Use a regex to parse text strings according to the pattern that you set in this box. If the regex pattern that you outline evaluates to
true
, the regex replacement pattern will run. - Regex replacement pattern: Outline in regex notation how you want to replace your string if the regex pattern that you outlined evaluates to
true
. Use capture groups to match subexpressions in this replacement regex.
For more information about regex replace and capture groups, see The Regular Expression Object Model: The Captured Group.
Note
As described in the Microsoft Entra documentation, you can't modify a restricted claim by using a policy. The data source can't be changed, and no transformation is applied when you're generating these claims. The group claim is still a restricted claim, so you need to customize the groups by changing the name. If you select a restricted name for the name of your custom group claim, the claim will be ignored at runtime.
You can also use the regex transform feature as a filter, because any groups that don't match the regex pattern will not be emitted in the resulting claim.
If the transform applied to the original groups claim results in a new custom claim, then the original groups claim will be omitted from the token. However, if the configured regex doesn't match any value in the original list, then the custom claim will not be present and the original groups claim will be included in the token.
After you add a group claim configuration to the User Attributes & Claims configuration, the option to add a group claim will be unavailable. To change the group claim configuration, select the group claim in the Additional claims list.
You can also configure group claims in the optional claims section of the application manifest.
In the portal, select Identity > Applications > App registrations > Select Application > Manifest.
Enable group membership claims by changing
groupMembershipClaims
.Valid values are:
Selection Description All
Emits security groups, distribution lists, and roles. SecurityGroup
Emits security groups and Microsoft Entra roles that the user is a member of in the group claim. DirectoryRole
If the user is assigned directory roles, they're emitted as a wids
claim. (A group claim won't be emitted.)ApplicationGroup
Emits only the groups that are explicitly assigned to the application and that the user is a member of. None
No groups are returned. (It's not case-sensitive, so none
also works. It can be set directly in the application manifest.)For example:
"groupMembershipClaims": "SecurityGroup"
By default, group
ObjectID
attributes will be emitted in the group claim value. To modify the claim value to contain on-premises group attributes, or to change the claim type to a role, use theoptionalClaims
configuration described in the next step.Set optional claims for group name configuration.
If you want the groups in the token to contain the on-premises Active Directory group attributes, specify which token-type optional claim should be applied in the
optionalClaims
section. You can list multiple token types:idToken
for the OIDC ID tokenaccessToken
for the OAuth/OIDC access tokenSaml2Token
for SAML tokens
Note
The
Saml2Token
type applies to tokens in both SAML1.1 and SAML2.0 format.For each relevant token type, modify the group claim to use the
optionalClaims
section in the manifest. TheoptionalClaims
schema is as follows:{ "name": "groups", "source": null, "essential": false, "additionalProperties": [] }
Optional claims schema Value name
Must be "groups"
.source
Not used. Omit or specify null
.essential
Not used. Omit or specify false
.additionalProperties
List of additional properties. Valid options are "sam_account_name"
,"dns_domain_and_sam_account_name"
,"netbios_domain_and_sam_account_name"
,"cloud_displayname"
, and"emit_as_roles"
.In
additionalProperties
, only one of"sam_account_name"
,"dns_domain_and_sam_account_name"
, or"netbios_domain_and_sam_account_name"
is required. If more than one is present, the first is used and any others are ignored.Some applications require group information about the user in the role claim. To change the claim type from a group claim to a role claim, add
"emit_as_roles"
to additional properties. The group values will be emitted in the role claim.To emit group display name for cloud-only groups, you can add
"cloud_displayname"
toadditional properties
. This option will work only when“groupMembershipClaims”
is set toApplicationGroup
Note
If you use
"emit_as_roles"
, any configured application roles that the user is assigned to will not appear in the role claim.
Emit groups as group names in OAuth access tokens in DNSDomainName\sAMAccountName
format:
"optionalClaims": {
"accessToken": [{
"name": "groups",
"additionalProperties": ["dns_domain_and_sam_account_name"]
}]
}
Emit group names to be returned in NetbiosDomain\sAMAccountName
format as the role claim in SAML and OIDC ID tokens:
"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"]
}]
}