Bill Fiddes [MSFT]

Lets get Started!

To enable the return of groups in a claim, there are two ways…

  1. Use the application registration manifest by enabling the groupMembershipClaims property…
    https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-app-manifest
  2. or if it’s a SAML application, you can enable it though the SSO configuration.

The steps on enabling groups claim is outlined in the following article…
https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims

Once enabled, groups will now be returned in the “groups” claim within a access token or ID token using OpenID Connect.

Important Note:

Id tokens will only contain the groups claim if the openid value is included in the scope parameter.

When using, the Azure Active Directory Authentication library (ADAL) for dotnet, by default you may not get the groups claim. You may need to add the scope claim with the openid value as an ExtraQueryParameter.

Moving forward…

The following groups claim description comes from https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens

Provides object IDs that represent the subject’s group memberships. These values are unique (see Object ID) and can be safely used for managing access, such as enforcing authorization to access a resource. The groups included in the groups claim are configured on a per-application basis, through the groupMembershipClaims property of the application manifest. A value of null will exclude all groups, a value of “SecurityGroup” will include only Active Directory Security Group memberships, and a value of “All” will include both Security Groups and Office 365 Distribution Lists.

Examples…

For example, if you are using OAuth2 and getting a access token for Microsoft Graph, the groups claim will not be returned. This is because the application registration of Microsoft Graph does not have the groupMembershipClaims enabled.

Keep in mind, only the audience of the access token should be consuming the access token. In this case, the audience is Microsoft Graph. Microsoft Graph currently has no need to know what groups a user is a member of.

In another example, if the audience is Azure Storage Explorer, this first-party application registration does in fact return groups because it does have groupMembershipClaims enabled. This is because Azure Storage Explorer allows you to assign groups to access its resources so it needs to know what groups a principal is a member of.

So, if you want to get the groups claim from an access token, ensure the audience is for your application registration. Then you can have your application request a access token for another resource like Microsoft Graph. Otherwise, you can use the ID token issued by Azure AD when using OpenID Connect.

An Access Token and ID Token will look something like this with the “groups” claim…

{
“typ”: “JWT”,
“alg”: “RS256”,
“x5t”: “{x5t-value}”,
“kid”: “{kid-value}”
}.{
“aud”: “{audience}”,
“iss”: “https://sts.windows.net/{tenant-id}/”,
…
“groups”: [ “group-id-1”, “group-id-2”,
…}.{signature}

There are some limitations…

GUID’s returned only.

By default, GUID’s are returned in the “groups” claim. If your group is synchronized to Azure AD using Azure AD Connect, you can then display the group name.

For more information about configuring the groups claim…
https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims

Otherwise, if they are not synchronized, you will only get the GUID. You will need to make a separate call to Microsoft Graph to retrieve another value like its Display Name.

The Microsoft Graph call will look something like this…

https://graph.microsoft.com/beta/users/{user-id}/memberOf

If using Azure AD Graph API (not recommended)….
https://graph.windows.net/{tenant-ID}/users/{user-ID}/getMemberObjects”

When using the OAuth2 implicit flow and the principal is a member of more than 5 groups…

Instead of getting a “groups” claim, you will get a “hasgroups” claim.

The following description is from https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens

“hasgroups” claim: If present, always true, denoting the user is in at least one group. Used in place of the groupsclaim for JWTs in implicit grant flows if the full groups claim would extend the URI fragment beyond the URL length limits (currently 6 or more groups). Indicates that the client should use the Graph to determine the user’s groups (https://graph.windows.net/{tenantID}/users/{userID}/getMemberObjects).

In this scenario, An Access Token and ID Token will look something like this with the “groups” claim…

{
“typ”: “JWT”,
“alg”: “RS256”,
“x5t”: “{x5t-value}”,
“kid”: “{kid-value}”
}.{
“aud”: “{audience}”,
“iss”: “https://sts.windows.net/{tenant-id}/”,
…
“hasgroups”: “true”,
…}.{signature}

For all other authentication flows…

For other flows, if the number of groups the user is in goes over a limit (150 for SAML, 200 for JWT), then an overage claim will be added to the claim sources pointing at the Graph endpoint containing the list of groups for the user. So, just like above, you will need to make a additional call to the Graph API endpoint to get the groups the user is a member of.

In this scenario, An Access Token and ID Token will look something like this with the “groups” claim…

{
“typ”: “JWT”,
“alg”: “RS256”,
“x5t”: “{x5t-value}”,
“kid”: “{kid-value}”
}.{
“aud”: “{audience}”,
“iss”: “https://sts.windows.net/{tenant-id}/”,
…

“_claim_names”: { “groups”: “src1” },

“_claim_sources”: {

“src1”: { “endpoint”: “https://graph.windows.net/{tenantID}/users/{userID}/getMemberObjects” }

},
…}.{signature}

Azure AD B2C

As for Azure AD B2C, when using user flow policies, the “groups” claim is not available. You will have to use the Graph API to get the list of groups the user is a member of.

Using Microsoft Graph to get a list of groups a user is a member of.

Even though today, the endpoints provided by the claims above when the user is a member of too many groups is using the Azure AD Graph endpoint, we actually recommend using Microsoft Graph as the Azure AD Graph is being deprecated.

You can use Microsoft Graph to get a list of groups the user is a member of by following the guidance provided in the following article…

https://docs.microsoft.com/en-us/graph/api/user-list-memberof?view=graph-rest-1.0

Essentially, the Microsoft Graph call will look something like this…

https://graph.microsoft.com/v1.0/users/john@contoso.com/memberOf

Leave a Comment