AdminSingle Sign-On

You are viewing the docs for Archestra v1.4. View the latest docs

Single Sign-On

Sign users in to Archestra with their workplace identity provider (IdP) and manage access permissions directly from your directory.

Single Sign-On (SSO) automates onboarding: users authenticate through your IdP, and Archestra provisions accounts and assigns roles and team memberships from directory claims.

Identity providers are an enterprise feature. See Pricing Model.

Supported Protocols

Archestra supports two SSO protocols:

  • OIDC (OpenID Connect): Modern OAuth 2.0 + OIDC for Microsoft Entra ID, Okta, Google, GitHub, GitLab, Auth0, and Keycloak.
  • SAML 2.0: Legacy enterprise identity providers that require SAML assertions.

Callback URLs

Configure the callback URL in your identity provider before enabling SSO in Archestra. The {ProviderId} path segment is case-sensitive and must match the Archestra provider ID (Okta, EntraID, Google, GitHub, GitLab, or your custom ID).

ProtocolProduction Callback URLLocal Development URL
OIDChttps://<domain>/api/auth/sso/callback/{ProviderId}http://localhost:3000/api/auth/sso/callback/{ProviderId}
SAML (ACS URL)https://<domain>/api/auth/sso/saml2/sp/acs/{ProviderId}http://localhost:3000/api/auth/sso/saml2/sp/acs/{ProviderId}

Sign-In Boundaries

Limit which accounts can sign in through an identity provider:

  • Allowed Email Domains: Enter comma-separated domains (such as company.com, subsidiary.com). Subdomains match automatically (eng.company.com matches company.com).
  • Downstream-only providers: Uncheck Use for Single Sign-On to use a provider solely for MCP tool token exchange. The provider remains hidden from the sign-in screen, and its role mapping rules never apply.

Change an Email Claim

For OIDC providers, keep User ID Claim unchanged when changing Email Claim. Archestra uses the provider and user ID to recognize an existing SSO user. A changed User ID Claim blocks every existing user's next sign-in.

With OIDC profile updates enabled, the user's next successful sign-in updates their email on the same account. Saving the mapping leaves their email and active sessions unchanged. If that account also has a password, use the updated email with the existing password afterward.

If the updated email belongs to a pending Microsoft Teams user who has never signed in, Archestra can reconcile that pending user automatically. Its supported chat history, resources, and team memberships move to the existing SSO user. An account with login credentials, an active session, ongoing work, or other owned resources requires manual resolution; sign-in reports an email conflict and preserves both users.

Role Mapping

Map directory attributes and groups to Archestra roles at each sign-in using Handlebars templates.

When a user signs in, Archestra tests the token claims against your mapping rules in order. The first rule whose template returns a non-empty string assigns its 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.

Template Helpers

HelperPurposeExample
includesCheck if an array contains a value (case-insensitive){{#includes groups "admins"}}true{{/includes}}
equalsString equality check{{#equals role "admin"}}true{{/equals}}
and / orBoolean logic{{#and dept title}}{{#equals dept "IT"}}true{{/equals}}{{/and}}
jsonParse JSON string or serialize value{{#with (json roles)}}{{#each this}}{{#equals this.name "admin"}}true{{/equals}}{{/each}}{{/with}}

For OIDC providers, ensure the ID token includes the groups claim. Many providers omit groups unless the groups scope is requested during authorization.

Team Sync

Automatically add and remove users from Archestra teams based on directory group memberships.

Sync creates direct membership in the mapped team, while preserving members added manually in Archestra.

  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 target team, and open External Group Sync.
  4. Enter the external group identifier (such as an Entra group object ID or Okta group name) and click Add.

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.

Troubleshooting

SymptomCauseFix
state_mismatchCookies blocked or mismatched callback URLEnable browser third-party cookies and verify the IdP redirect URI matches the case-sensitive {ProviderId}.
account not linkedMismatched or unverified emailConfirm the user signs in with the email address registered on Archestra, and verify the email in the IdP.
"Account Belongs to Someone Else"The identity provider gave this email to a different person, such as a new hire who inherited a former employee's addressSomeone with member:delete removes the previous account in Settings → Users with Remove. The person then signs in again and gets a new, empty account.
account_not_found (SAML)Missing user attributesConfigure your SAML IdP to include NameID in emailAddress format, plus email, firstName, and lastName.
signature_validation_failedExpired or rotated SAML certificateRe-download your IdP SAML metadata and update the certificate in Archestra.
User missing team membershipGroup claim omitted or identifier typoConfirm the IdP sends the group claim in the ID token and that the group name in Settings → Teams matches verbatim.