Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

Automatic roles with Active Directory groups

Enterprise plans

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.

How it works

When a user authenticates through SSO, Builder:

  1. Receives the user's AD group memberships from your identity provider.
  2. Scans for groups following the naming pattern builder-{space-id}-{role}, where space-id is your Public API Key.
  3. 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.

When to use AD group role mapping

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

Prerequisites

Before configuring AD group role mapping:

AD group naming convention

Active Directory groups must follow a specific naming pattern for Builder to recognize them:

builder-{SPACE_ID|ORG_ID}-{ROLE_NAME}

Naming pattern components

  • 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.

Examples

Space-specific roles:

builder-abc123def456-admin builder-abc123def456-editor builder-abc123def456-developer

Organization-specific roles:

builder-xyz789ghi012-admin builder-mainorg456-designer

Valid role names

Use the following default role names in your AD groups. Your Organization may also have custom roles:

  • admin: full administrative access
  • editor: content editing permissions
  • developer: development and code access
  • designer: design tool access
  • contributor: 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

Configure your identity provider to include AD group information in authentication responses.

Step 1: add group claims

For SAML:

  • Claim name: adGroups or groups
  • Claim format: array of group names
  • Filter: include only groups starting with builder- (recommended)

For OIDC:

  • Scope: include groups scope
  • Claim: groups or custom group claim
  • Format: array of group distinguished names or simple names

Step 2: filter groups (recommended)

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.

Provider-specific configuration examples

Microsoft Entra ID (Azure AD)

In your Enterprise application:

  1. Go to Single sign-on > Attributes & Claims.
  2. Click Add a group claim.
  3. Select the groups to include in the token.
  4. For Source attribute, choose Group ID or sAMAccountName.
  5. In Advanced options, select Filter groups and enter builder-* as the filter.

Okta

In your Okta application:

  1. Go to the Sign On tab.
  2. Click Edit next to OpenID Connect ID Token.
  3. In the Groups claim type section, select Filter.
  4. Set the filter to: Starts with: builder-
  5. For Groups claim name, enter groups.

Alternatively, use a Groups Claim Expression:

Arrays.flatten(user.groups.startsWith("builder-"))

Google Workspace

In your SAML app configuration:

  1. Go to Attribute mapping.
  2. Add a new attribute:
  3. Configure group filtering to include only groups starting with builder-.

Step 3: test your configuration

  1. Create a test AD group following the naming convention: builder-{your-space-id}-developer.
  2. Add a test user to this group.
  3. Have the test user sign in using SSO.
  4. In Builder, navigate to your Space's user management.
  5. Verify the test user received the Developer role automatically.

Multi-Space role assignment

Builder supports automatic assignment to multiple Spaces based on AD group memberships.

Root Organizations

When the SsoUseAdGroups feature is enabled for a root Organization:

  1. Builder scans all Spaces within the root Organization.
  2. For each Space, it looks for matching AD groups: builder-{space-id}-{role}.
  3. 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 space789

Individual Organizations

For standalone Organizations, Builder:

  1. Looks for AD groups matching the Organization Private API Key: builder-{org-id}-{role}.
  2. Assigns the specified role to the user in that Organization.

Security considerations

Group name validation

  • 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.

Access control

  • 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.

Common issues and solutions

Role not assigned

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 SsoUseAdGroups feature 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.

Incorrect Space assignment

  • 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.

Groups not being sent from identity provider

  • 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

Debugging

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.

Example identity provider configurations

Microsoft Entra ID (Azure AD)

SAML assertion example:

<Attribute Name="groups"> <AttributeValue>builder-abc123def456-admin</AttributeValue> <AttributeValue>builder-xyz789ghi012-editor</AttributeValue> </Attribute>

Azure AD group claim configuration:

  1. Navigate to your Enterprise Application
  2. Select Single sign-on > Attributes & Claims
  3. Add a group claim with source attribute Group ID
  4. Apply filter: Starts with: builder-

Okta

OIDC token claim:

{ "groups": [ "builder-abc123def456-admin", "builder-xyz789ghi012-editor" ] }

Group expression in Okta:

Arrays.flatten(user.groups.startsWith("builder-"))

Google Workspace

SAML attribute mapping:

<Attribute Name="groups"> <AttributeValue>builder-abc123def456-admin</AttributeValue> <AttributeValue>builder-xyz789ghi012-editor</AttributeValue> </Attribute>

Get help

For additional assistance with AD group role mapping:

Was this article helpful?