After setting up SSO, you can automate user role assignments in Builder based on Active Directory (AD) group memberships. When users sign in with SSO, they automatically receive roles in specific Spaces or Organizations based on their AD groups, which eliminates manual role assignment.
When a user authenticates through SSO, Builder:
- Receives the user's AD group memberships from your identity provider.
- Scans for groups following the naming pattern
builder-{space-id}-{role}, wherespace-idis your Public API Key. - Automatically assigns the specified roles to the user in the corresponding spaces.
Example: If a user is in the AD group builder-abc123-editor, they automatically receive the Editor role in space abc123.
This feature is ideal for Organizations that:
- Manage large teams with many users
- Already use Active Directory groups to control access across applications
- Want to reduce manual user management overhead in Builder
- Need to ensure role assignments stay synchronized with your existing access control policies
Before configuring AD group role mapping:
- SSO must be configured: set up SSO integration with your identity provider. See SSO with Builder and Your Identity Provider, SSO with Microsoft Entra ID, SSO with Google Workspace, or SSO with Okta for instructions.
- Feature flag enabled: contact Builder support to enable the
SsoUseAdGroupsfeature flag for your Organization. - AD groups created: create Active Directory groups and assign users.
- Admin access: you need administrative access to your identity provider configuration.
Active Directory groups must follow a specific naming pattern for Builder to recognize them:
builder-{SPACE_ID|ORG_ID}-{ROLE_NAME}builder-: required prefix (case-sensitive){SPACE_ID|ORG_ID}: the Space Public API Key or Organization Private API Key where the role should be assigned.{ROLE_NAME}: the role to assign that exactly matches a valid role name in Builder.
Space-specific roles:
builder-abc123def456-admin
builder-abc123def456-editor
builder-abc123def456-developerOrganization-specific roles:
builder-xyz789ghi012-admin
builder-mainorg456-designerUse the following default role names in your AD groups. Your Organization may also have custom roles:
admin: full administrative accesseditor: content editing permissionsdeveloper: development and code accessdesigner: design tool accesscontributor: basic contribution access
Important: Role names in AD groups must exactly match the role names configured in your Builder Space. Role matching is case-sensitive.
Configure your identity provider to include AD group information in authentication responses.
- Claim name:
adGroupsorgroups - Claim format: array of group names
- Filter: include only groups starting with
builder-(recommended)
- Scope: include
groupsscope - Claim:
groupsor custom group claim - Format: array of group distinguished names or simple names
For security and performance, configure your identity provider to send only groups starting with builder-:
Filter: groups starting with "builder-"This prevents unnecessary group data transmission and processing.
In your Enterprise application:
- Go to Single sign-on > Attributes & Claims.
- Click Add a group claim.
- Select the groups to include in the token.
- For Source attribute, choose Group ID or sAMAccountName.
- In Advanced options, select Filter groups and enter
builder-*as the filter.
In your Okta application:
- Go to the Sign On tab.
- Click Edit next to OpenID Connect ID Token.
- In the Groups claim type section, select Filter.
- Set the filter to:
Starts with: builder- - For Groups claim name, enter
groups.
Alternatively, use a Groups Claim Expression:
Arrays.flatten(user.groups.startsWith("builder-"))In your SAML app configuration:
- Go to Attribute mapping.
- Add a new attribute:
- Configure group filtering to include only groups starting with
builder-.
- Create a test AD group following the naming convention:
builder-{your-space-id}-developer. - Add a test user to this group.
- Have the test user sign in using SSO.
- In Builder, navigate to your Space's user management.
- Verify the test user received the Developer role automatically.
Builder supports automatic assignment to multiple Spaces based on AD group memberships.
When the SsoUseAdGroups feature is enabled for a root Organization:
- Builder scans all Spaces within the root Organization.
- For each Space, it looks for matching AD groups:
builder-{space-id}-{role}. - Users automatically receive roles in all Spaces where matching groups exist.
Example:
User's AD groups:
- builder-space123-admin
- builder-space456-editor
- builder-space789-developer
Result: User automatically receives:
- Admin access to space123
- Editor access to space456
- Developer access to space789For standalone Organizations, Builder:
- Looks for AD groups matching the Organization Private API Key:
builder-{org-id}-{role}. - Assigns the specified role to the user in that Organization.
- Only groups starting with
builder-are processed. - Role names must exactly match configured roles in Builder.
- Invalid role names are ignored and logged for security auditing.
- Users only receive access to Spaces with matching AD group membership.
- Existing permissions are preserved; AD groups add roles rather than replacing them.
- Failed role assignments are logged for administrative review.
Possible causes and solutions:
- Incorrect group name format: verify the AD group name follows the exact pattern
builder-{space-id}-{role}with correct spacing and hyphens. - Role doesn't exist: check that the role name exists in the target space and matches exactly (case-sensitive).
- User not in group: confirm the user is a member of the correct AD group in your directory.
- Feature not enabled: verify the
SsoUseAdGroupsfeature flag is enabled for your organization. Contact Builder.io support if needed. - Group claim not configured: make sure your identity provider is sending group information in the SAML assertion or OIDC token.
- Double-check the Space Public API Key in the AD group name.
- Confirm the space exists and is accessible.
- Verify you're using the correct Public API Key, not a display name.
- Review your identity provider's configuration for group claims
- Check group filtering settings
- Examine the SAML assertion or OIDC token to verify group data is included
- Test with your identity provider's token inspection tools
Contact Builder support to enable debug logging for your Organization. When enabled, the following information is logged:
- AD groups received from the identity provider.
- Group pattern matching results.
- Role assignment attempts and outcomes.
- Invalid group names or roles encountered.
This logging helps identify configuration issues quickly.
SAML assertion example:
<Attribute Name="groups">
<AttributeValue>builder-abc123def456-admin</AttributeValue>
<AttributeValue>builder-xyz789ghi012-editor</AttributeValue>
</Attribute>Azure AD group claim configuration:
- Navigate to your Enterprise Application
- Select Single sign-on > Attributes & Claims
- Add a group claim with source attribute
Group ID - Apply filter:
Starts with: builder-
OIDC token claim:
{
"groups": [
"builder-abc123def456-admin",
"builder-xyz789ghi012-editor"
]
}Group expression in Okta:
Arrays.flatten(user.groups.startsWith("builder-"))SAML attribute mapping:
<Attribute Name="groups">
<AttributeValue>builder-abc123def456-admin</AttributeValue>
<AttributeValue>builder-xyz789ghi012-editor</AttributeValue>
</Attribute>For additional assistance with AD group role mapping:
- Review SSO with Builder and Your Identity Provider for general SSO setup.
- Check your identity provider's documentation for group claim configuration.
- Contact Builder support for feature-specific questions or to enable the
SsoUseAdGroupsfeature flag.