Skip to main content

Configure Google Workspace Group Claims

This guide explains how to configure Google Workspace to include group membership in SAML assertions. These group claims enable automatic team assignment in AI Gateway based on users' Google Workspace group memberships.

Overview​

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

  1. Create groups in Google Workspace Admin Console
  2. Configure your SAML app to include group membership in assertions
  3. Map the Google group email addresses to AI Gateway teams

Prerequisites​

  • Google Workspace Admin Console access with super administrator permissions
  • SAML application configured for AI Gateway SSO
  • Groups created in Google Workspace for team mapping

Step 1: Create Groups in Google Workspace​

  1. Sign in to the Google Admin Console
  2. Go to Directory → Groups
  3. Click Create group

Configure Group Settings​

  1. Enter a Group name (e.g., "Engineering", "Sales", "Design")
  2. Enter a Group email (e.g., engineering@yourdomain.com)
  3. Add a Description (optional)
  4. Click Next

Set Access Settings​

  1. Choose an Access type (Public, Team, or Restricted)
  2. Configure who can join the group
  3. Click Create group

Add Members to Groups​

  1. Click on the group name to open it
  2. Click Members → Add members
  3. Enter email addresses of users to add
  4. Click Add

Step 2: Configure SAML App Group Membership​

  1. In Google Admin Console, go to Apps → Web and mobile apps
  2. Click on your AI Gateway SAML application
  3. Click SAML attribute mapping or navigate to the attribute mapping section

Configure Group Membership​

  1. Scroll down to the Group membership (optional) section

  2. You'll see the message: "Group membership information can be sent in the SAML response if the user belongs to any of the groups you add here."

  3. Click on Search for a group dropdown

  4. Select the groups you want to include:

    • Select each group that should be sent in the SAML response
    • Only users who are members of these groups will have that membership included

  5. Verify the App attribute field is set to Groups

  6. Click Save

Selecting Groups

Only select groups that are relevant for team-based access control. Users will only receive group claims for groups they are actually members of.

Step 3: Configure Group Attribute in AI Gateway​

After configuring Google Workspace, you need to tell AI Gateway which attribute contains group information.

Update SSO Settings​

  1. Access your tenant configuration in the SSO management system
  2. Navigate to SSO Mapping → Group Attribute Mapping
  3. Enter Groups in the attribute name field (matching the App attribute from Step 2)
  4. Click Save

Verify Configuration​

After saving, the AI Gateway portal should show:

  • Group Attribute Mapping: Groups (instead of "Not configured")

Step 4: Configure AI Gateway Teams​

Create teams in AI Gateway using the Google group email addresses:

  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 Google group email address (e.g., engineering@yourdomain.com)
  5. Press Enter to add the group
  6. Click Create

Example Team Mappings​

AI Gateway TeamSSO Group (Google Group Email)
Engineeringengineering@yourdomain.com
Salessales@yourdomain.com
Designdesign@yourdomain.com
Productproduct@yourdomain.com

Troubleshooting​

Groups Not Appearing for Users​

Issue: Users don't see team-restricted resources after logging in

Solutions:

  1. Verify the user is a member of the Google group
  2. Check that the group is selected in the SAML app's group membership section
  3. Have the user log out and log back in (group membership is evaluated at login)
  4. Verify the group email matches exactly in the AI Gateway team SSO mapping

Group Attribute Not Configured​

Issue: AI Gateway shows "Group Attribute Mapping: Not configured"

Solutions:

  1. Ensure you entered Groups in the Group Attribute Mapping field in SSO settings
  2. Verify the SAML app has the App attribute set to Groups
  3. Save the configuration and refresh the page

Wrong Group Format​

Issue: AI Gateway team matching fails even with correct group

Solutions:

  1. Use the full group email address (e.g., engineering@yourdomain.com)
  2. Check for case sensitivity - group emails are typically lowercase
  3. Verify there are no extra spaces in the SSO Group mapping

User in Multiple Groups​

Issue: User should have access to multiple teams' resources

Expected behavior: Users who are members of multiple Google groups will automatically be assigned to all corresponding AI Gateway teams and have access to all their resources.

Security Considerations​

  • Principle of least privilege: Only include groups in SAML assertions that are needed for access control
  • Group management: Control group membership carefully as it directly affects resource access
  • Regular audits: Review group memberships and team mappings periodically
  • Naming conventions: Use consistent, descriptive group names and emails

Next Steps​

After configuring group claims:

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

Additional Resources​