Configure group claims for applications using Azure Active Directory - Microsoft Entra (2023)

Azure Active Directory (Azure AD) can provide user group membership information in tokens for use within applications. This feature supports three main patterns:

• Groups identified by the Azure AD object identifier (OID) attribute.
• Groups identified bysAMA account nametheGroupSIDfeature for groups and users synchronized by Active Directory
• Groups identified by the Display Name attribute for cloud-only groups

Important warnings about this function

• Support for using itsAMA account nameand security identifier (SID) attributes synchronized from an on-premise installation is designed to enable migration of existing applications from Active Directory Federation Services (AD FS) and other identity providers. Groups managed in Azure AD do not contain the necessary attributes to issue these claims.

• To avoid the limit on the number of groups, if your users have a large number of group memberships, you can limit the groups broadcast in the claims to the relevant groups for the application. Read more about broadcast groups assigned to the app forJWT tokensandSAML tokens. If groups cannot be assigned to your applications, you can also configure agroup filterto reduce the number of groups emitted in the claim. Group filtering applies to tokens issued for applications where group claims and filtering are configured inCorporate applicationsblade at the gate.

• Group claims have a limit of five groups if the token is issued via the silent stream. Tokens requested via the implicit stream will have a"hasgroups":trueclaim only if the user belongs to more than five groups.

• We recommend that you base in-app authorization on application roles instead of groups when:

  • You develop a new application or an existing application can be configured for it.
  • No support is required for nested groups.

  Using application roles limits the amount of information that must be entered into the token, is more secure, and separates user assignment from application configuration.

Group claims for applications transported by AD FS and other identity providers

Many applications configured to authenticate with AD FS rely on group membership information in the form of Windows Server Active Directory group attributes. These features are the groupsAMA account name, which can be qualified by the domain name or the Windows security group ID (GroupSID). When the application integrates with AD FS, AD FS uses theTokenGroupsfunction to retrieve the group memberships for the user.

An application moved from AD FS needs claims in the same format. Group and role claims emitted by Azure AD may contain the qualifying domainsAMA account namecharacteristic or theGroupSIDattribute was synchronized from Active Directory and not from the group's Azure ADobject identifierFeature.

The supported formats for group claims are:

• AD Group Azure ObjectId: Available for all groups.
• sAMA account name: Available for groups synchronized by Active Directory.
• NetbiosDomain\sAMAccountName: Available for groups synchronized by Active Directory.
• DNSDomainName\sAMAccountName: Available for groups synchronized by Active Directory.
• On-premise group security ID: Available for groups synchronized by Active Directory.

Options for apps to consume group information

Applications can call the Microsoft Graph group endpoint to get group information about the authenticated user. This call ensures that all groups a user is a member of are available, even when a large number of groups are involved. Group enumeration is then independent of token size constraints.

However, if an existing application expects to consume group information through claims, you can configure Azure AD with various claim formats. Consider the following options:

• When using group membership for in-app authorization, it is preferable to use the groupObject IDFeature. The teamObject IDThe attribute is immutable and unique to Azure AD. It is available for all groups.

  (Video) Microsoft Entra .. the new Azure Active Directory portal

• If you use the on-premise groupsAMA account nameattribute for authorization, use domain-appropriate names. Reduces the chance of name collisions.sAMA account namecan be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with an Azure AD tenant, there is a possibility for more than one group to have the same name.

• Consider usingapplication rolesto provide a level of indirection between group membership and the application. The application then makes internal authorization decisions based on the role claims on the token.

• If the application is configured to receive group attributes synchronized from Active Directory and a group does not contain these attributes, it will not be included in the claims.

• Group claims on tokens include nested groups unless you use the option to restrict group claims to application-assigned groups.

  If a user is a member of Group B and Group B is a member of Group A, then the group claims for the user will contain both Group A and Group B. When users in an organization have a large number of group memberships, the number of groups listed in the token may increase the size of the token. Azure AD limits the number of groups it will emit in a token to 150 for SAML assertions and 200 for JWT. If a user is a member of more than one group, the groups are skipped. Instead, a link to the Microsoft Graph endpoint is included to get group information.

  See Also

  Azure AD Connect: Troubleshooting sync errors - Microsoft EntraAzure AD Connect Health - Alert List - Microsoft EntraAzure AD Connect: Traversal Authentication Issues - Microsoft EntraCertificate renewal for Microsoft 365 and Azure AD users - Microsoft Entra

Prerequisites for using group attributes synchronized by Active Directory

Group membership claims can be issued in tokens for any group if you use theObjectIdform. To use group claims in other forms outside of the groupObjectId, groups must be synchronized from Active Directory through Azure AD Connect.

To configure Azure AD to emit group names for Active Directory groups:

1. Synchronize group names from Active Directory

   Before Azure AD can broadcast the group names or on-premises group SID to group or role claims, you must synchronize the required attributes from Active Directory. You must be running Azure AD Connect version 1.2.70 or later. Previous versions of Azure AD Connect since 1.2.70 will synchronize group objects from Active Directory, but will not include the required group name attributes.

2. Configure the application registration in Azure AD to include group claims on tokens

   You can set up group claims atCorporate Applicationspart of the portal or using the application manifest atRegistration of ApplicationsUnity. To configure group claims in the application manifest, seeConfigure Azure AD application enrollment for group attributeslater in this article.

Add group claims to tokens for SAML applications using SSO configuration

To configure group claims for a gallery or non-gallery SAML application through single sign-on (SSO):

1. OpenCorporate Applications, select the application in the list, selectSingle Sign On configurationand then selectUser Properties and Claims.

2. ChooseAdd a group claim.

   

3. Use the options to choose which groups to include in the token.

   

   Selection	Description
   All groups	Broadcast security groups and distribution lists and roles.
   Security teams	Casts security groups that the user is a member of in the groups claims.
   Directory roles	If the user has been assigned directory roles, they are emitted as awidsrequirement. (The group's claim will not be dismissed.)
   Groups assigned to the application	Broadcasts only the groups explicitly assigned to the application and of which the user is a member. Recommended for large organizations due to the group number limit per token.

   • For example, to broadcast all security groups that the user is a member of, selectSecurity teams.

     

     To broadcast groups using Active Directory attributes synced from Active Directory instead of Azure ADobject identifierfeatures, select the required format from theSource attributedrop down list. Only groups synchronized from Active Directory will be included in the claims.

     (Video) Microsoft Entra / Azure AD 2 0 Explained with Full Demo

     

   • To broadcast only groups assigned to the application, selectGroups assigned to the application.

     

     The groups assigned to the application will be included in the token. Other groups the user is a member of will be skipped. 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 theCorporate Applicationslist. Then chooseUsers and Groupsfrom the left menu of the application.

     For more information about managing group assignment in applications, seeAssign a user or group to an enterprise application.

Casts cloud-only group display name to token

You can configure the group claim to include the group display name for cloud-only groups.

1. OpenCorporate Applications, select the application in the list, selectSingle Sign On configurationand then selectUser Properties and Claims.

2. If you have already configured group claims, select fromAdditional ClaimsUnity. Otherwise, you can add the group claim as described in the previous steps.

3. For the type of group emitted in the token selectGroups assigned to the application:

   See Also

   Tutorial: Integrating Azure Active Directory Single Sign-On (SSO) with Jamf Pro - Microsoft Entra

   

4. To emit group display name for cloud groups only, atSource attributedrop down menu select itCloud-only group display names:

   

5. For a hybrid setup, to emit an on-premises group attribute for synchronized groups and a display name for cloud groups, you can select the desired on-premises sources attribute and select the check boxBroadcast group name for cloud-only groups:

   

Set advanced options

Customize group claim name

You can modify how group claims are broadcast using the settings belowAdvanced options.

If you chooseCustomize the group claim name, you can specify a different claim type for group claims. Enter the claim type inNamecontext and the optional namespace for the claim atNamespacebox.

Some applications require that group membership information appear in the role claim. You can optionally cast user groups as roles by selecting thisThey emit groups as role claimscontrol box.

Group filtering

Group filtering allows precise control over the list of groups included as part of the group claim. When a filter is configured, only groups that match the filter will be included in the group claim sent to this application. The filter will be applied to all groups regardless of the group hierarchy.

You can configure the filters to be applied to the group display name orSAMA account nameFeature. The following filtering functions are supported:

• Prefix: Matches the beginning of the selected attribute.
• Conclusion: Matches the end of the selected attribute.
• Contains: Matches any location in the selected attribute.

Team transformation

Some applications may require groups in a different format than how they are represented in Azure AD. To support this requirement, you can apply a transformation to each group that will be emitted in the group claim. You accomplish this by allowing a regular expression (regex) and a replacement value to be configured in custom group claims.

\

• Regex pattern: Use a regex to parse text strings according to the pattern specified in this box. If the regex pattern you describe evaluates totrue, the regex replacement pattern will be executed.
• Regex replacement pattern: Describe in regex notation how you want to replace your string if the regex pattern you described evaluates totrue. Use capture groups to match subexpressions to this replacement regex.

For more information about regex replacement and fetch groups, seeThe regular expression object model: The captured group.

Edit group claim configuration

After adding a group claim configuration toUser Properties and Claimsconfiguration, the option to add group claim will not be available. To change the group claim configuration, select the group claim atAdditional Claimslist.

Configure Azure AD application enrollment for group attributes

You can also configure group claims atoptional claimspart of itapplication statement.

1. In the portal, selectAzure Active Directory>Registration of Applications>Select Apply>Manifest.

2. Enable group membership claims by switchinggroup Membership Claims.

   Valid values ​​are:

   Selection	Description
   All	Broadcasts security groups, distribution lists, and roles.
   Security Group	Casts Azure AD security groups and roles that the user is a member of in the group claim.
   DirectoryRole	If the user has been assigned directory roles, they are emitted as awidsrequirement. (A group claim will not be sent.)
   ApplicationGroup	Broadcasts only the groups explicitly assigned to the application and of which the user is a member.
   No one	Groups are not refunded. (It is not case sensitive, sono oneit also works. It can be set directly in the application manifest.)

   For example:

   "groupMembershipClaims": "SecurityGroup"

   By default, groupObject IDthe attributes will be broadcast in the group claim price. To modify the claim value to contain on-premises group attributes or to change the claim type to a role, useoptional claimsconfiguration described in the next step.

3. Set optional claims for the group name configuration.

   If you want the groups in the token to contain the attributes of the on-premises Active Directory group, specify which optional token type claim should apply tooptional claimsUnity. You can list many types of tokens:

   • idTokenfor the OIDC ID token
   • access tokenfor the OAuth/OIDC access token
   • Saml2Tokenfor SAML tokens

   Note

   TheSaml2Tokenthe formula applies to tokens in SAML1.1 and SAML2.0 format.

   For each relevant token type, modify the group claim to use itoptional claimsunity in the manifesto. Theoptional claimsthe scheme is as follows:

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

   Optional claim form	value
   name	It must be"groups".
   source	It's not being used. Omission or specificationzero.
   essential	It's not being used. Omission or specificationfalse.
   additional properties	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".

   Inadditional properties, only one of"sam_account_name","dns_domain_and_sam_account_name", the"netbios_domain_and_sam_account_name"required. If there is more than one, the first one 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"in additional properties. Group values ​​will be emitted in the role claim.

   To emit a group display name for cloud-only groups, you can add"cloud_displayname"toadditional properties. This option will only work when"Group Membership Claims"It has been setApplicationGroup

   Note

   If you are using"emit_as_roles", any configured application roles to which the user is assigned will not appear in the role claim.

Examples

They emit groups as group names in OAuth access tokensDNSDomainName\sAMAccountNameform:

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

They emit group names that will be returnedNetbiosDomain\sAMAccountNameformat as a role claim in SAML and OIDC identifier 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"] }]}

Next steps

• Add authorization using groups and group claims to an ASP.NET Core web application (code sample)
• Assign a user or group to an enterprise application
• Configure role claims