Skip to main content

Enterprise SSO With SAML and OpenID Connect

Enterprise SSO is configured by an Organization Owner, Admin, or Identity Admin when enabled for the deployment. Login supports SP-initiated SAML 2.0 and standards-based OpenID Connect (OIDC). SCIM directory provisioning separately supports Organization users, groups, and administrator-configured group-to-role/Team mappings. IdP-initiated SAML login is not supported. Federated logout is an optional connection setting described below.

SSO belongs to the company-level Organization, not to an individual Team. A successful JIT login creates or restores only the Organization membership allowed by policy; Team membership is assigned separately, including through configured SCIM group mappings. Required SSO protects both member workspaces governed by the Organization and every Team inside it.

Before configuration​

Confirm the deployment uses one canonical HTTPS PUBLIC_SITE_URL, secure session and CSRF cookies, the configured proxy SSL header, and a Django Site domain matching the public URL. Keep the enterprise_sso switch disabled while deploying dependencies and migrations. Enable it only when the deployment check passes.

For a dedicated company deployment, set DT_TENANCY_MODE=single_organization and set DT_SINGLE_ORGANIZATION_SLUG to the active Organization slug. Non-staff users are then pinned to that company, the login page links directly to its active SSO connection, and users still receive their own workspace alongside any Teams they join. Staff retain the recovery path. Hosted deployments keep the default multi_organization mode and use email-domain discovery or the stable /accounts/sso/<organization-slug>/ URL.

The organization must have at least one globally unique email domain. Shared domains cannot be routed between organizations in this release.

Provider values​

Open Governance → Access → Identity and use the Enterprise SSO controls. Sensitive changes can require recent authentication. Create a draft and copy the generated provider values; do not guess callback URLs from another deployment.

For SAML, give the IdP the SP entity ID/metadata URL and ACS URL shown in the card. Configure a persistent subject identifier and an email attribute. AuthnRequests are signed with the draft's generated RSA-2048 certificate. The IdP must sign the response or assertion with SHA-256-compatible algorithms.

For OIDC, register the callback URL shown in the card. The client must permit the authorization-code flow, PKCE S256, and openid profile email scopes. The provider must return sub, email, and a valid signed ID token; returning email_verified is strongly recommended.

Safe activation sequence​

  1. Add the Organization's email domain, publish the displayed DNS TXT name and value, and choose Verify after DNS propagation. Domain ownership must be verified before activation.
  2. Create a SAML or OIDC draft.
  3. Enter the HTTPS metadata/issuer URL and protocol credentials.
  4. Refresh provider configuration. Resolve any endpoint, issuer, certificate, or metadata error.
  5. Use Test and complete the real provider round trip within 15 minutes. A test validates the provider but does not create a user, identity, membership, or application session.
  6. Activate within 24 hours of the successful test. Start in optional enforcement mode.
  7. Ask an active owner or admin to use the tenant SSO URL successfully.
  8. Have an Owner with a usable account password create and securely store an emergency recovery kit outside the identity provider.
  9. Change enforcement to required only after the successful privileged sign-in and recovery readiness checks pass.

When a sensitive action asks a member to confirm their identity, members without an account password are sent to the Organization's SSO sign-in instead of the password prompt; signing in through the active connection again satisfies the check. Members with a password confirm with it as before.

Agent restore, personal-agent release, sandbox reset, and sandbox software-policy publish/retry share the same SSO-aware confirmation. These controls use the acting user's selected Organization only while that user has active membership and the Organization has an active SSO connection. In personal workspaces and global staff screens, they can instead use the user's latest linked enterprise SSO identity recorded in the current browser session, subject to current membership and connection status. Staff viewing context and the agent's owning Organization do not choose the user's identity provider. An unavailable connection or disabled enterprise_sso switch retains the existing password fallback; it does not bypass confirmation.

The confirmation window for these controls remains 15 minutes. After sign-in, agent controls return to the agent's settings; sandbox policy controls return to System settings → Sandbox software, where the operator reviews and resubmits. Existing role, deployment, cleanup and acknowledgement requirements still apply. Deploy updated web processes to apply this routing fix; no schema migration or new feature flag is required.

Existing-members-only is the default provisioning policy. Invite-required consumes a current pending invitation and preserves its role. JIT creates a Member by default (Viewer is the only alternative) when a seat is available. JIT never reactivates a removed membership.

None of the provisioning modes automatically adds a user to a Team. Organization Owners, Admins, and Agent Admins already have implicit Team administration; ordinary members need an explicit Team grant or an applicable SCIM group mapping.

Certificate and credential rotation​

Active protocol configuration is immutable. Use Clone to draft, update the draft, refresh it, and run a new provider test. Activation switches the organization atomically to the replacement and invalidates grants issued by the former connection. Keep the old IdP signing certificate in metadata during a rollover; multiple signing certificates are accepted.

Federated logout​

Federated logout defaults to disabled, including on cloned connections. An Owner, Admin, or Identity Admin can enable it in the connection's Federated logout controls. The same controls are available to platform staff. Refresh configuration first if the provider's logout endpoint has just been added to its metadata.

For SAML, configure the displayed SAML logout URL as the service provider's HTTP-Redirect Single Logout Service. The IdP must advertise an HTTPS HTTP-Redirect logout endpoint, accept requests and responses signed with the SP certificate, and sign its own logout messages with RSA SHA-256, SHA-384, or SHA-512. Login assertions must supply NameID and SessionIndex for application-initiated logout. NameID can differ from the attribute used as the account's subject. Both application-initiated and IdP-initiated logout are supported; HTTP-POST, SOAP, and artifact logout bindings are not.

For OIDC, the provider must advertise an HTTPS end_session_endpoint. Register the exact displayed Post-logout redirect URL in the OIDC client before enabling logout. The app submits the verified ID token as a hint using a browser POST. OIDC front-channel and back-channel logout notifications are not supported.

Enabling logout invalidates existing SSO-backed access to this Organization, including the administrator's SSO session. Sign in through SSO again to capture fresh provider-session information. Personal and unrelated Organization access remain available. This reauthentication requirement also applies when SSO enforcement is optional; ordinary password-only sessions are not converted into required-SSO sessions.

Sign out always ends the local browser session first. It then attempts every enabled provider represented in that browser, starting with the most recent SSO sign-in. Providers may also sign the user out of other applications. The app displays whether SAML logout was confirmed, an OIDC provider returned, or provider logout was incomplete. An OIDC return does not independently verify the status of other application sessions.

The browser must return from each provider to attempt the next one. If a provider interrupts the flow, return to /accounts/logout/complete/ within 15 minutes and choose Skip interrupted provider and continue. This attempts the remaining providers without claiming the skipped provider signed out. Missing session identifiers, expired configuration, cancellation, and provider errors leave local sign-out effective. A later callback never ends a new local login.

An authenticated SAML IdP logout removes matching Organization access across browsers. With SessionIndex, only matching provider sessions are revoked; without it, all applicable sessions for the NameID and connection are revoked. Personal access, other Organizations, and different provider sessions remain available. Revoked Organization chat subscriptions lose access as well.

Disabling federated logout stops new provider attempts and incoming SAML logout requests. Requests already sent may finish during their 15-minute return window. Logout outcomes and session revocations appear in the existing security audit stream without protocol payloads or tokens.

Users cannot change their own email while an enterprise identity is linked. Staff may use the identity migration API only after verifying the request and the new email domain. Migration and unlink actions are audited. Unlinking removes the allauth social account and invalidates the organization SSO grant; it does not remove the user's local account or organization membership.

Metadata and key health​

Provider configuration refreshes every six hours. A transient refresh failure keeps the last-known-good configuration. SAML metadata becomes unusable after an explicit validUntil. Metadata without an expiry remains usable, but a seven-day stale cache raises a high-severity staff warning. OIDC signing keys are fetched through the guarded outbound client and retried once when a token references a newly rotated key.

Troubleshooting​

  • No enterprise sign-in found: confirm the submitted email's normalized domain belongs to exactly one organization and that the organization has an active connection.
  • Dedicated deployment still shows email discovery: confirm both tenancy settings identify an active Organization and that the Organization has an active, usable SSO connection.
  • Provider configuration unavailable: inspect the safe metadata error code. URLs must be HTTPS and resolve only to public addresses; redirects are checked too.
  • Test succeeds but activation fails: repeat the test if it is older than 24 hours. For required mode, first activate optional and have an active owner or admin sign in.
  • Email or subject conflict: do not auto-merge accounts. Verify the identity in the IdP and use the audited staff migration/unlink operation.
  • Seat limit reached: add a seat, remove or revoke the correct member/invite, then retry. Failed SSO provisioning leaves no user, identity, or membership behind.
  • Repeated SAML failures: verify issuer, audience/entity ID, ACS destination, clock synchronization, response/assertion signature, and signing certificate rollover.
  • Repeated OIDC failures: verify exact issuer, callback URL, client secret, sub, nonce/state, PKCE support, scopes, and current JWKS.

Recovery and rollback​

An Organization Owner with an account password can create an emergency recovery kit from Identity. The eight single-use codes are shown once. Download or copy them into a secure location outside the identity provider, along with the displayed recovery page URL. Creating a replacement kit immediately invalidates all codes from the previous kit.

During an identity-provider outage:

  1. Open the recovery page saved with the kit.
  2. Enter the active Owner's email, account password, and an unused recovery code.
  3. Within the ten-minute recovery session, use the offered action to make SSO optional.
  4. Sign in through the ordinary account flow, repair and test the identity connection, and restore required enforcement when ready.

The recovery session cannot sign someone into the workspace or reveal Organization data. It only permits the restricted enforcement-recovery action. A code is consumed when the recovery session begins, and recovery use is audited and notifies active Owners. A removed Owner, missing password, invalid code, or non-required connection cannot use this path.

System administrators retain an operator recovery path when the Owner kit cannot be used. To roll back while normal administration is available, make enforcement optional or deactivate the active connection. With federated logout disabled, sign-out ends the application session only. If enabled provider logout fails, the local session still ends; complete sign-out at the provider separately if needed.

Machine authentication and execution are not gated by interactive SSO proof: organization API keys, device relays, Remote MCP, inbound integrations, and background agent execution continue to operate.

Last updated on