Skip to main content

Entra ID Groups Claim Overage

Goal

When mapping Entra ID security groups to DynamoAI roles, users who belong to many groups in Microsoft Entra ID may sign in successfully but not receive the org-level roles you configured with Advanced Claim to Role mappers. This guide explains why that happens, how to confirm it, and how to fix it.

Applies only to claim-based role mapping

This issue affects deployments that use Advanced Claim to Role mappers keyed on the groups claim. Deployments that use a single Hardcoded Role mapper for every IdP user are not affected.

Background

How group-based mappers work​

During IdP brokering, Keycloak reads claims from the ID token Entra ID returns and evaluates each Advanced Claim to Role mapper against the groups claim. If a mapper's regex matches one of the group Object IDs in that claim, Keycloak assigns the corresponding DynamoAI role.

This flow is documented in Adding Mappers — Mapping Entra ID Security Groups to DynamoAI Roles. It assumes the ID token always contains a groups array with the security group Object IDs you mapped.

Entra ID group limits in tokens​

Microsoft Entra ID caps how many groups it embeds directly in a JWT:

Token typeGroup limit
JWT (ID or access token)200 groups
SAML150 groups
Implicit flow (ID token only)6 groups

When a user belongs to more groups than the limit, or when the token would exceed size limits, Entra ID omits the groups claim entirely. Instead, the token may include an overage indicator that tells the receiving application to query Microsoft Graph for the user's full group membership:

{
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://graph.microsoft.com/v1.0/users/{user-id}/getMemberObjects"
    }
  }
}

For implicit-flow tokens, the overage indicator is a hasgroups: true claim instead of _claim_names.

See Configure group claims for applications and Access token claims reference — groups for Microsoft's documentation on this behavior.

Why Keycloak mappers fail​

Keycloak's IdP mappers evaluate claims present in the ID token at login time. They do not follow _claim_sources endpoints or call Microsoft Graph on your behalf.

When the groups claim is missing:

  • Advanced Claim to Role mappers find nothing to match.
  • The user still receives the hardcoded all-users group mapper (if configured).
  • The user does not receive org-level roles tied to Entra group membership.

From the user's perspective, sign-in succeeds but access looks wrong — similar to a permissions problem, but the root cause is a missing claim in the upstream token, not incorrect Keycloak configuration.

Do not treat a missing claim as zero group membership

A user with no groups claim in the token may still belong to dozens or hundreds of Entra groups. Always investigate overage before concluding the user is not in the mapped group.

Symptoms

Users affected by group overage typically show this pattern:

  1. Sign-in through Entra ID completes without error.
  2. The user appears under Users in the dynamo-ai realm.
  3. The user is in the all-users group (from the hardcoded group mapper).
  4. The user is missing one or more org-level roles that their Entra group membership should grant.
  5. Other users in the same tenant who belong to fewer groups receive the expected roles.

The issue is most common in large organizations where users inherit many security groups (department, location, distribution lists, nested memberships, and so on) beyond the groups you use for DynamoAI authorization.

Diagnosis

Step 1: Decode the ID token​

Capture the ID token Entra ID returns during sign-in. You can use browser developer tools on the redirect back to Keycloak, or a tool such as jwt.ms.

Check the payload for:

What you seeMeaning
"groups": ["<guid>", ...] with your mapped group Object ID presentGroup claim is working; look elsewhere (regex typo, wrong Object ID, sync mode).
No groups claim, but _claim_names / _claim_sources or hasgroups: trueGroup overage — this guide's fix applies.
No groups claim and no overage indicatorsGroups claim not configured on the app registration — see Adding Mappers — Step 1.

Step 2: Confirm group count in Entra ID​

In the Azure Portal, open the affected user under Microsoft Entra ID → Users and review Groups. If the user is a member of a large number of security groups (approaching or exceeding 200, or simply many more than the handful you use for DynamoAI), overage is the likely cause.

Step 3: Verify Keycloak mappers​

In the dynamo-ai realm, open the Entra identity provider and confirm:

  • Advanced Claim to Role mappers use claim key groups.
  • The regex values contain the correct Entra security group Object IDs (not display names).
  • No duplicate Hardcoded Role mapper grants the same role unconditionally.

If the token lacks groups entirely, mapper configuration alone cannot fix the problem.

Solution

Limit which groups Entra ID emits in the token by configuring the groups claim to include only groups assigned to the dynamoai-idp enterprise application, then assign the security groups you use for DynamoAI role mapping. This keeps the groups claim within token limits and lets Keycloak mappers continue to work without Graph API integration.

1. Change the groups claim source​

In Customer-Entra-ID (Azure Portal):

  1. Open the dynamoai-idp app registration.

  2. Go to Token configuration.

  3. If a groups claim already exists, remove it and re-add it (or edit via the application manifest — see below).

  4. Click Add groups claim.

  5. Under group types, select Groups assigned to the application (not Security groups or All groups).

    Microsoft recommends this option for large organizations because it avoids the 200-group JWT limit. See Configure groups optional claims — Groups assigned to the application.

  6. Under customize token properties for the ID token, choose Group ID (required for Object ID–based Keycloak mappers).

  7. Save.

2. Assign the authorization groups to the enterprise application​

The groups claim only includes groups assigned to the application, so each Entra security group that should drive DynamoAI role assignment must be explicitly assigned:

  1. Go to Microsoft Entra ID → Enterprise applications.

  2. Search for and open dynamoai-idp.

  3. Go to Users and groups.

  4. Click Add user/group.

  5. For each security group referenced in your Keycloak Advanced Claim to Role mappers, add that group (not individual users).

    Example: if mappers reference groups DynamoAI-Developers and DynamoAI-Admins, assign both groups here.

  6. Save.

You do not need to assign every group the user belongs to in the directory — only the groups whose Object IDs appear in your Keycloak mapper regexes.

3. Retest​

  1. Have an affected user sign out and sign in again through Entra ID.
  2. Decode the new ID token and confirm the groups claim is present and contains the expected Object IDs.
  3. In Keycloak (dynamo-ai realm → Users), confirm the user received the mapped org-level roles.

What not to do

ApproachWhy it does not work for DynamoAI
Query Microsoft Graph from Keycloak at loginKeycloak IdP mappers do not support Graph lookups via _claim_sources.
Assume the user has no groups when groups is absentOverage omits the claim; membership may still include your mapped groups.
Add every directory group to the enterprise applicationDefeats the purpose of limiting emitted groups and may reintroduce overage.

Verification checklist

After applying the fix:

  • ID token from a previously affected user contains a groups claim (decode at jwt.ms).
  • The groups claim includes the Object ID(s) referenced in Keycloak Advanced Claim to Role mappers.
  • No _claim_names, _claim_sources, or hasgroups overage indicators appear in the token.
  • Keycloak shows the expected org-level roles on the user after re-login.
  • A user not in any mapped group still receives all-users but not claim-mapped roles.

Related Guides

Last updated on