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).
| Protocol | Production Callback URL | Local Development URL |
|---|---|---|
| OIDC | https://<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.commatchescompany.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.
- In Settings → Identity Providers, edit your provider and select Role Mapping.
- Add one or more Mapping Rules with a template and target roles.
- Set Default Roles for new users who match no rule.
- Optional: Turn on Strict Mode to block sign-in for users who match no rule.
- Optional: Turn on Skip Role Sync to evaluate roles only on first sign-in, leaving subsequent role changes to manual administration.
Template Helpers
| Helper | Purpose | Example |
|---|---|---|
includes | Check if an array contains a value (case-insensitive) | {{#includes groups "admins"}}true{{/includes}} |
equals | String equality check | {{#equals role "admin"}}true{{/equals}} |
and / or | Boolean logic | {{#and dept title}}{{#equals dept "IT"}}true{{/equals}}{{/and}} |
json | Parse 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.
- In the provider's Team Sync tab, verify Enable Team Sync is on.
- If your IdP uses custom group claim paths, set Groups Handlebars Template (e.g.
{{#each groups}}{{this}},{{/each}}). Otherwise, Archestra checksgroups,group,memberOf,roles, andteamsin order. - Go to Settings → Teams, click Edit on target team, and open External Group Sync.
- 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:
- Disable password sign-in: Set
ARCHESTRA_AUTH_DISABLE_BASIC_AUTH=truein the backend environment and restart. This hides the email/password form and requires SSO. - Disable invitations: Set
ARCHESTRA_AUTH_DISABLE_INVITATIONS=trueto disable manual user invite workflows.
If SSO fails while password authentication is disabled, recover via the command line with Account Security.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
state_ | Cookies blocked or mismatched callback URL | Enable browser third-party cookies and verify the IdP redirect URI matches the case-sensitive {ProviderId}. |
account not linked | Mismatched or unverified email | Confirm 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 address | Someone 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_ (SAML) | Missing user attributes | Configure your SAML IdP to include NameID in emailAddress format, plus email, firstName, and lastName. |
signature_ | Expired or rotated SAML certificate | Re-download your IdP SAML metadata and update the certificate in Archestra. |
| User missing team membership | Group claim omitted or identifier typo | Confirm the IdP sends the group claim in the ID token and that the group name in Settings → Teams matches verbatim. |