Role Mapping

Archestra supports automatic role assignment based on user attributes from your identity provider using Handlebars templates. This lets you map SSO groups, roles, or other claims to Archestra roles (Admin, Member, or any custom role you have defined).

How role mapping works

1. When a user authenticates via SSO, Archestra receives user attributes from the identity provider's ID token (for OIDC) or SAML assertions
2. These attributes are evaluated against your configured mapping rules in order
3. The first rule that matches determines the user's Archestra role
4. If no rules match, the user is assigned the configured default role (or Member if not specified)

Configuring role mapping

When creating or editing an SSO provider, expand the Role Mapping (Optional) section:

1. Mapping Rules — add one or more rules. Each rule has:

   • Handlebars Template: a template that renders to a non-empty string when the rule should match
   • Archestra Role: the role to assign when the template matches

2. Default Role — the role assigned when no rules match (defaults to "member")

3. Strict Mode — when enabled, denies user login if no mapping rules match. Useful when you want to ensure that only users with specific IdP attributes can access Archestra. Without strict mode, users who don't match any rule are simply assigned the default role.

4. Skip Role Sync — when enabled, the user's role is only determined on their first login. Subsequent logins will not update their role, even if their IdP attributes change. This allows administrators to manually adjust roles after initial provisioning without those changes being overwritten on next login.

Handlebars template examples

Templates should render to any non-empty string (like "true") when the rule matches. The following custom helpers are available:

Example templates:

Tip: templates should output any non-empty string when matching. The text "true" is commonly used but any output works.

Handling JSON string claims

Some identity providers (like Okta) may send complex claims as JSON strings rather than native arrays. For example:

{
  "roles": "[{\"name\":\"Application Administrator\"},{\"name\":\"archestra-admin\"}]"
}

To parse and match against JSON string claims, use the json helper with #with:

{{#with (json roles)}}{{#each this}}{{#equals
      this.name "archestra-admin"
    }}true{{/equals}}{{/each}}{{/with}}

This template:

1. Parses the JSON string into an array using (json roles)
2. Sets the parsed array as context using #with
3. Iterates through each role object using #each
4. Checks if any role's name property matches

Troubleshooting

Role not being assigned correctly:

1. Check your IdP's configuration to ensure the expected claims/attributes are being sent
2. Use your IdP's token introspection or SAML assertion viewer to verify the actual data
3. Ensure your Handlebars template syntax is correct
4. Rules are evaluated in order — make sure your most specific rules come first

Missing groups claim:

• For OIDC: verify your IdP is configured to include groups in the token/userinfo
• For SAML: check that group attributes are included in the assertion and properly mapped

Template always returns empty:

• Check for typos in claim/attribute names — they are case-sensitive in the template
• Ensure your IdP is sending the expected claims in the ID token
• The includes helper handles null/undefined arrays gracefully

You can test Handlebars templates at tryhandlebarsjs.com using your actual ID token claims as input. To inspect the actual claims your IdP sends, paste the ID token into jwt.io.

See also

• Team Sync — automatically add or remove users from Archestra teams based on IdP group membership
• Identity Providers — provider list and SSO setup