Single Sign-On

Let people sign in with their workplace accounts. Test one sign-in before requiring SSO for everyone. This is an Enterprise feature.

Add a Provider

For provider-specific values, use the Entra ID or Okta guide.

1. Register Archestra as a web application in your identity provider.
2. Set its callback URL. The {ProviderId} is case-sensitive: Okta, EntraID, Google, GitHub, GitLab, or your custom Provider ID.

3. Open Settings → Identity Providers, enable the provider, and enter its issuer, client ID, and client secret or SAML metadata.
4. Set Allowed Email Domains if sign-in should be restricted. Subdomains match too: company.com allows eng.company.com.
5. Click Create Provider and test sign-in in an incognito window.

For a provider used only for MCP token exchange, clear Use for Single Sign-On. It stays off the sign-in screen and does not assign roles.

Role Mapping

Rules evaluate token claims at each sign-in. The first Handlebars template returning a non-empty string assigns its target roles.

1. In Settings → Identity Providers, edit your provider and select Role Mapping.
2. Add one or more Mapping Rules with a template and target roles.
3. Set Default Roles for new users who match no rule.
4. Optional: Turn on Strict Mode to block sign-in for users who match no rule.
5. Optional: Turn on Skip Role Sync to evaluate roles only on first sign-in, leaving subsequent role changes to manual administration.

For example, map this rule to Admin:

{{#includes groups "admins"}}true{{/includes}}

For OIDC, ensure the ID token includes the group claim; your provider may require the groups scope.

Team Sync

Put people in the right teams, with the right team role, straight from their directory groups. Link the group platform-leads to a team as Admin, and everyone in it joins that team as a team admin when they sign in.

1. In the provider's Team Sync tab, verify Enable Team Sync is on.
2. If your IdP uses custom group claim paths, set Groups Handlebars Template (e.g. {{#each groups}}{{this}},{{/each}}). Otherwise, Archestra checks groups, group, memberOf, roles, and teams in order.
3. Go to Settings → Teams, click Edit on the team, and open Team Sync.
4. Click Link a group, enter the group identifier (such as an Entra group object ID or Okta group name), pick a Team role, and press Enter.

The group appears in the team's list. On their next sign-in, its members join the team with that role.

What to know:

• Each sign-in adds and removes synced members to match their groups, and makes them Admin while a linked group grants it. Sync takes Admin away only if sync gave it, so a promotion by hand sticks. Members added by hand are never changed.
• With more than one identity provider, a link matches only sign-ins through the provider you picked for it.
• A person in several linked groups of one team gets Admin if any of those links grants it.

Enforcing SSO

Lock down authentication to your identity provider once SSO sign-in is tested and verified:

1. Disable password sign-in: Set ARCHESTRA_AUTH_DISABLE_BASIC_AUTH=true in the backend environment and restart. This hides the email/password form and requires SSO.
2. Disable invitations: Set ARCHESTRA_AUTH_DISABLE_INVITATIONS=true to disable manual user invite workflows.

If SSO fails while password authentication is disabled, recover via the command line with Account Security.

Change an Email Claim

Keep User ID Claim unchanged when changing Email Claim. With OIDC profile updates enabled, the next sign-in updates the existing account's email. Saving the mapping does not change active sessions. An email already used by another account may require resolving that conflict first.

Troubleshooting