Skip to main content

Configure Microsoft Entra Group Claims

This guide explains how to configure Microsoft Entra ID (formerly Azure AD) to include group membership claims in authentication tokens. These group claims enable automatic team assignment in AI Gateway based on users' Entra ID group memberships.

Overview​

When users authenticate via SSO, AI Gateway reads their group memberships from the authentication token. To enable this:

  1. Configure Entra ID to include group claims in SAML assertions or OIDC tokens
  2. Map the Entra group names/IDs to AI Gateway teams

Prerequisites​

  • Microsoft Entra ID tenant with appropriate admin permissions
  • Enterprise Application configured for AI Gateway SSO
  • Security groups created in Entra ID for team mapping

Step 1: Find Your Enterprise Application​

  1. Sign in to the Microsoft Entra admin center
  2. Navigate to Identity → Applications → Enterprise applications
  3. Search for your AI Gateway SSO application
  4. Click on the application to open its settings

Step 2: Configure Group Claims​

  1. In your Enterprise Application, click Single sign-on in the left menu
  2. In the Attributes & Claims section, click Edit

Add Groups Claim​

  1. Click + Add a groups claim
  2. Choose which groups to include:
OptionDescriptionRecommended For
Security groupsInclude all security groups the user is a member ofMost scenarios, works with Free tier
Directory rolesInclude directory roles assigned to the userAdmin role-based access
Groups assigned to the applicationOnly groups explicitly assigned to this Enterprise AppEnterprise scenarios (requires P1/P2 license)
All groupsInclude all group typesComprehensive access but may hit token limits
Azure AD Free Tier Limitation

The "Groups assigned to the application" option requires Azure AD Premium P1 or P2 license. If you're on the Free tier, select "Security groups" instead.

  1. Click Add to save the groups claim

Configure Claim Format​

After adding the groups claim, configure how group information is sent:

  1. Under Source attribute, select one of:
    • Group ID - Sends the group's Object ID (GUID format)
    • sAMAccountName - Sends the group's display name (if synced from on-prem AD)
    • Cloud-only group display name - Sends the Entra group display name
Choosing the Right Format
  • Group ID (GUID) is most reliable but less human-readable
  • Display Name is easier to recognize but may change if groups are renamed

For production, consider using Group ID for stability and documenting which GUID maps to which team.

  1. For Customize the name of the groups claim (optional):

    • SAML: Change the claim name if needed (default: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups)
    • OIDC: The claim appears as groups in the token

  2. Click Save

Step 3: Find Group Names or IDs​

To map Entra groups to AI Gateway teams, you need the exact group identifier.

Finding Group Object IDs​

  1. In Microsoft Entra admin center, go to Identity → Groups → All groups
  2. Search for your group
  3. Click on the group to open its details
  4. Copy the Object ID (GUID format)

Finding Group Display Names​

  1. In Microsoft Entra admin center, go to Identity → Groups → All groups
  2. The Display name column shows the human-readable name
  3. Copy the exact name (case-sensitive)

Step 4: Configure AI Gateway Teams​

Now create teams in AI Gateway using the group identifiers:

  1. In AI Gateway portal, navigate to Access → Teams
  2. Click Create Team
  3. Enter a team name and description
  4. In SSO Groups, enter the Entra group identifier (Group ID or Display Name)
  5. Press Enter to add the group
  6. Click Create

Troubleshooting​

Groups Not Appearing in Token​

Issue: SAML assertion or JWT doesn't contain group claims

Solutions:

  1. Verify the groups claim is configured in Attributes & Claims
  2. Check that the user is actually a member of at least one group
  3. For "Groups assigned to application" - verify groups are assigned to the Enterprise App
  4. Check if you hit the groups limit (see below)

Groups Claim Limit​

Issue: Only some groups appear, or _claim_names and _claim_sources appear instead

Cause: Entra ID limits groups in tokens:

  • SAML: 150 groups
  • JWT: 200 groups (or 6 for implicit flow)

Solutions:

  1. Use "Groups assigned to the application" to limit which groups are included
  2. Use group filtering to include only relevant groups
  3. Configure Entra to emit a groups overage claim and fetch groups via Graph API

Wrong Group Format​

Issue: AI Gateway team matching fails even with correct group

Solutions:

  1. Verify the exact format (GUID vs display name) matches what's configured in the team
  2. Check for case sensitivity in display names

Security Considerations​

  • Principle of least privilege: Only include necessary groups in tokens
  • Token size: Large numbers of groups increase token size and latency
  • Group naming: Use consistent, descriptive group names
  • Regular audits: Review group memberships and team mappings periodically
  • Sensitive groups: Consider excluding highly sensitive groups from token claims

Next Steps​

After configuring group claims:

  1. Create Teams in AI Gateway using your Entra group identifiers
  2. Assign MCP Servers and Personas to teams
  3. Test with a non-admin user to verify access control works correctly

Additional Resources​