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

When a user authenticates via SSO, Archestra receives user attributes from the identity provider's ID token (for OIDC) or SAML assertions
These attributes are evaluated against your configured mapping rules in order
The first rule that matches determines the user's Archestra role
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, select the Role Mapping section:

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
Default Role — the role assigned when no rules match (defaults to "member")
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.
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:

Helper	Description
`includes`	Check if an array includes a value (case-insensitive)
`equals`	Check if two values are equal (case-insensitive for strings)
`contains`	Check if a string contains a substring (case-insensitive)
`and`	Logical AND — true if all values are truthy
`or`	Logical OR — true if any value is truthy
`exists`	True if the value is not null/undefined
`notEquals`	Check if two values are not equal

Example templates:

Template	Description
`{{#includes groups "admins"}}true{{/includes}}`	Match if "admins" is in the groups array
`{{#equals role "administrator"}}true{{/equals}}`	Match if role claim equals "administrator"
`{{#each roles}}{{#equals this "platform-admin"}}true{{/equals}}{{/each}}`	Match if "platform-admin" is in roles array
`{{#and department title}}{{#equals department "IT"}}true{{/equals}}{{/and}}`	Match IT department users with a title set
`{{#with (json roles)}}{{#each this}}{{#equals this.name "admin"}}true{{/equals}}{{/each}}{{/with}}`	Match role name in JSON string claim (see below)

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

OIDC group claims

For OIDC providers, group-based rules only work if the ID token contains the group claim. Many IdPs do not include groups with the default openid, email, and profile scopes. If your template reads groups, add the provider's group scope (commonly named groups) and configure the IdP to emit that claim in the ID token.

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:

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

Troubleshooting

Role not being assigned correctly:

Check your IdP's configuration to ensure the expected claims/attributes are being sent
Use your IdP's token introspection or SAML assertion viewer to verify the actual data
Ensure your Handlebars template syntax is correct
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 ID token, and that the SSO provider requests the groups scope required by your IdP
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

When editing an existing OIDC provider, use the built-in template tester in the Role Mapping section to test rules against your latest decoded ID token claims.