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

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

• Groups identified by their Azure AD Object Identifier (OID) attribute.
• Groups identified bysAMAaccountNameorGroup IDAttribute for groups and users synchronized with Active Directory
• Groups identified by the display name attribute for cloud-only groups

Important warnings for this function

• Usage supportsAMAaccountNameand Security Identifier (SID) attributes, which are synchronized locally, are intended to migrate existing applications from Active Directory Federation Services (AD FS) and other identity providers. Managed groups in Azure AD do not contain the attributes required to issue these requests.

• To avoid limiting the number of groups when your users have a large number of group memberships, you can limit the groups broadcast in requests to only relevant groups for the application. Learn more about publishing application-assigned groupsJWT-tokenISAML-token. If assigning groups to your applications is not an option, you can also configure itgroup filterto reduce the number of groups issued in the request. Group filtering applies to tokens issued to applications that have group claims and configured filteringbusiness applicationsBlade in the portal.

• Group claims have a limit of five groups when issuing tokens via the implicit stream. Tokens requested via an implicit stream have a"has groups": trueSearch only if the user belongs to more than five groups.

• We recommend that in-app authorization be based on application roles rather than groups when:

  • You are developing a new application or an existing application can be configured for it.
  • Nested group support is not required.

  Using application roles limits the amount of information that needs to go into the token, is more secure, and separates user assignment from application configuration.

Bulk requirements for applications migrating from 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 attributes form a groupsAMAaccountName, which are represented by a domain name or Windows group security identifier (Group ID). If the application is connected to AD FS, AD FS usesTokengruppenA function to obtain group membership for a user.

An application moved from AD FS needs requests in the same format. Requirements for groups and roles issued by Azure AD may include domain qualificationsAMAaccountNameattribute or thatGroup IDThe attribute is synchronized from Active Directory, not from an Azure AD groupobject identificationAttribute.

Supported formats for group claims are:

• ObjectId grupe Azure AD: Available for all groups.
• sAMAaccountName: Available to synchronize groups from Active Directory.
• NetbiosDomain\sAMAaccountName: Available to synchronize groups from Active Directory.
• DNSDomainName\sAMAaccountName: Available to synchronize groups from Active Directory.
• The security identifier of the local group: Available to synchronize groups from Active Directory.

Options for apps to use group information

Applications can call the Microsoft Graph group endpoint to retrieve group information for an authenticated user. This call ensures that all groups the user is a member of are available, even if a large number of groups are involved. Bulk enumeration is then independent of token size limits.

However, if an existing application expects to use group information via requests, you can configure Azure AD with different request formats. Consider the following options:

• If you use group membership for in-app authorization, it is preferable to use a groupobject identificationAttribute. Grupaobject identificationThe attribute is immutable and unique in Azure AD. It is available for all groups.

  (Video) Microsoft Entra Deep Dive: Azure Active Directory - Groups

• If you use a local groupsAMAaccountNameAuthorization attribute, use domain-qualified names. Reduces the possibility of name conflicts.sAMAaccountNamecan be unique within an Active Directory domain, but when more than one Active Directory domain is synchronized with an Azure AD tenant, there is a possibility that multiple groups will have the same name.

• Think about its useapplication rolesto provide an intermediate layer between group membership and the application. The application then makes internal authorization decisions based on the role request in the token.

• If an application is configured to retrieve group attributes synchronized from Active Directory, and the group does not contain those attributes, it will not be included in requests.

• Group requests in tokens include nested groups unless you use the option to limit group requests to application-assigned groups.

  If the user is a member of Group B, and Group B is a member of Group A, the group requests for the user will include both Group A and Group B. If the organization's users have a large number of group memberships, the number of groups specified in the token may increase the size of the token. Azure AD limits the number of groups emitted in a token to 150 for SAML assertions and 200 for JWTs. If the user is a member of more than one group, the groups are omitted. Instead, a connection to a Microsoft Graph endpoint is included to retrieve group information.

  See Also

  Troubleshooting managed feature storage - Azure Machine Learning

Prerequisites for using group attributes synchronized from Active Directory

Group membership requests can be issued in tokens for each group if you useobject identificationFormat. To use group requests in formats other than "group".object identification, groups from Active Directory must be synchronized via Azure AD Connect.

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

1. Synchronize group names from Active Directory

   Before Azure AD can broadcast group names or local group SIDs in group or role requests, you must synchronize the required attributes from Active Directory. You must be running Azure AD Connect version 1.2.70 or later. Versions of Azure AD Connect earlier than 1.2.70 synchronize group objects from Active Directory, but do not include the required group name attributes.

2. Configure application registration in Azure AD to include group requests in tokens

   You can configure group claims inBusiness applicationssection of the portal or by using the manifest of the application inApplication registrationsSection. For information about configuring group requests in the application manifest, seeConfigure Azure AD application registration for group attributeslater in this article.

Add group requests to SAML application tokens using SSO configuration

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

1. OpenBusiness applications, select an application in the list, selectSingle sign-on configuration, and then selectUser Properties and Claims.

2. ChooseAdd a group request.

   

3. Use the options to select the groups you want to include in the token.

   

   Choice	Description
   All groups	Returns security groups and distribution lists and roles.
   security groups	Returns the security groups to which the user in the group request belongs.
   noun roles	If the user is assigned directory roles, they are logged aswidsclaim. (The group request was not issued.)
   Groups assigned to the application	Returns only groups that are explicitly assigned to the application and of which the user is a member. Recommended for large organizations due to the limit on the number of groups in a token.

   • For example, select all security groups that the user is a member ofsecurity groups.

     

     To broadcast groups that use Active Directory attributes synchronized from Active Directory instead of Azure ADobject identificationAttributes, select the format you wantThat attributedrop down list. Only groups synchronized from Active Directory are included in the requests.

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

     

   • Select to exit only the groups assigned to the applicationGroups assigned to the application.

     

     Groups assigned to the application are included in the token. Other groups of which the user is a member are omitted. This option ignores nested groups and requires the user to be a direct member of the group assigned to the application.

     To change the groups assigned to an application, select the applicationBusiness applicationsA list. Then chooseUsers and groupsfrom the left menu of the application.

     For more information about managing application group assignments, seeAssign a user or group to a business application.

Broadcast the friendly cloud-only group name in the token

You can configure group claiming to include a group display name for cloud-only groups.

1. OpenBusiness applications, select an application in the list, selectSingle sign-on configuration, and then selectUser Properties and Claims.

2. If you have already configured group requests, select themAdditional claimsSection. Otherwise, you can add a group claim as described in the previous steps.

3. Select the type of group broadcast in the tokenGroups assigned to the application:

   

4. To output group display names for cloud groups only, uThat attributeSelect from the drop-down listFriendly names for cloud-only groups:

   

5. In a hybrid setup, to broadcast local group attributes for sync groups and friendly names for cloud groups, you can select the local source attribute you want and check the boxPrint group name for cloud-only groups:

   

Set advanced options

Customize the group request name

You can change how group claims are issued using the following settingsExtended options.

If you chooseCustomize the group request nameyou can make a different type of claim for group claims. Enter the request typeTo dofield and optional namespace for request uimenski spaceBox.

Some applications require group membership information to appear in a role request. You can optionally print user groups as roles by selecting the followingExpose groups as role requestscheckbox.

group filtering

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

You can configure filters that apply to a display name or group display nameSAMAaccountNameAttribute. The following filtering operations are supported:

• prefix: Corresponds to the beginning of the selected attribute.
• Suffix: Matches the end of the selected attribute.
• Contains: Matches any location in the selected attribute.

Group transformation

Some applications may require groups to be in a different format than how they are represented in Azure AD. To support this request, you can apply a transformation to each group emitted in a group request. You can achieve this by allowing regular expression (regex) and wildcard configuration for custom group requests.

\

• Regex-Muster: Use a regular expression to parse text strings according to the pattern you set in this field. If the regular expression pattern you sketched returns a valueSHE'S RIGHT, a regular expression replacement pattern is performed.
• Regular expression replacement pattern: Indicate in regular expression notation how you want to replace your string when the regular expression pattern you're describing evaluates toSHE'S RIGHT. Use capture groups to match subexpressions in this replacement regular expression.

For more information about regular expression replacement and capture groups, seeRegular expression object model: recorded group.

Edit the group request configuration

After adding the group requests configuration to theUser Properties and ClaimsConfiguration, option to add group request is not available. To change the group request configuration, select the group request inAdditional claimsDescription.

Configure Azure AD application registration for group attributes

You can also configure group claims inoptional statementssection ofapplication manifest.

1. Choose on the portalAzure Active Directory>Application registrations>Select an application>Manifest.

2. Enable group membership requirements by changing themGroup membership requirements.

   Valid values ​​are:

   Choice	Description
   already	Returns security groups, distribution lists, and roles.
   security group	Returns the security groups and Azure AD roles that the user belongs to in the group request.
   noun role	If the user is assigned directory roles, they are logged aswidsclaim. (A group request is not issued.)
   application group	Returns only groups that are explicitly assigned to the application and of which the user is a member.
   no	No group is coming back. (Therefore it is not case sensitive.)noIt also works. It can be set directly in the application manifest.)

   For example:

   „groupMembershipClaims“: „SecurityGroup“

   Group by defaultobject identificationAttributes are returned in group request values. To change the request value to include the local group attribute or to change the type of request to a role, useoptionalClaimsConfiguration as described in the next step.

3. Set optional group name configuration requirements.

   If you want groups in the token to contain Active Directory local group attributes, specify which optional token type request to apply tooptionalClaimsSection. You can specify multiple token types:

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

   Note

   TheSaml2TokenThe type refers to tokens in SAML1.1 and SAML2.0 format.

   For each relevant token type, change the group request to useoptionalClaimssection in the manifest. TheoptionalClaimsThe scheme is as follows:

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

   Electoral scheme of rights	Wert
   To do	It must be"Group".
   They	It has not been used. Omit or specifyNull.
   important	It has not been used. Omit or specifyINACCURATELY.
   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“, I"cast_as_roles".

   Uadditional properties, just one of„sam_account_name“,„dns_domain_and_sam_account_name“, or„netbios_domain_and_sam_account_name“needed. If there is more than one, the first one is used and all others are ignored.

   Some applications require group information about the user in the role request. To change the request type from a group request to a role request, add"cast_as_roles"to other properties. The group values ​​are output in the role request.

   To print the group display name for cloud-only groups, you can add„cloud_displayname“Doadditional properties. This option only works if"Requirements for group membership"it is set toapplication group

   Note

   ako korositie"cast_as_roles", any configured application roles to which the user is assigned will not appear in the role request.

examples

Emit groups as group names in OAuth access tokensDNSDomainName\sAMAaccountNameFormat:

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

Output group names to returnNetbiosDomain\sAMAaccountNameFormat as a role request 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“] }]}

Next steps

• Adding authorization using groups and group requests to an ASP.NET Core web application (code example)
• Assign a user or group to a business application
• Configure the role requirements