Single Sign-On (SAML)

The mental model

Three separate levers, on purpose:

• A connection is how your members sign in. A SAML connection lets people authenticate with your IdP. By itself it admits no one.
• A domain assignment is who signs in that way. Routing a verified domain through an active connection sends every @domain sign-in to your IdP — and that assignment is also the org's consent to provision new @domain users on their first SSO login (independent of the domain's User Auto-Join policy, which only governs password/Google self-signup).
• Enforce SSO is whether anything else is accepted. With enforcement on, members on the assigned domain must have signed in through your IdP to use this organization. It never blocks the login itself — see Enforcement below.

Sign-in is email-routed: on the login page, members open Sign in with SSO, type their work email, and are sent to the right IdP automatically (home-realm discovery). There is no per-connection sign-in URL to distribute.

Set up a connection

Settings → Single Sign-On (organization owner/admin; changing SSO config requires a recently re-authenticated session). An organization can hold multiple connections — e.g. a different IdP per email domain.

The flow is verify your domain → save → test → activate — activation routes the domain automatically, so there is no separate assignment step for the common case:

1. Verify your email domain first (on the Domains page) — with a DNS TXT record, or by a confirmation email to one of the domain's standard admin mailboxes (admin@, postmaster@, webmaster@, …). Verification is mandatory before SSO because sign-in routing is global: an unverified domain must never be able to capture another company's logins — a successful SAML handshake proves control of an IdP, not of the domain.
2. Add connection. Pick the verified domain the connection will authenticate, then the page shows the values your IdP admin registers on their side:
   • ACS URL / Redirect URI
   • SP Entity ID
   • Name ID format → EMAIL
   • the attribute mapping (below), and a downloadable SP metadata XML
3. Enter what your IdP publishes — explicit fields, no metadata import:
   • Connection name (a label, e.g. "Okta — acme.com")
   • SAML SSO URL (the IdP's sign-on endpoint)
   • SAML Issuer (the IdP's entity ID)
   • X.509 signing certificate (PEM, pasted) Save — the connection is now Configured but not yet live.
4. Test SSO (required before you can activate): enter a test user's email on the connection's domain, open the test sign-in in a new tab, complete it at your IdP, then press Check result. A successful round-trip marks the connection tested.
5. Activate. Activation routes the connection's domain through it immediately — from then on, sign-ins for that domain can use your IdP, and new users on it are provisioned into the org on first SSO login. (Passwords keep working until you turn on Enforce SSO.) The Domain routing table remains as the override for special cases — several connections, or moving a domain between them.

Editing the connection's core fields (URL / issuer / certificate) resets it to configured — re-test before it can be active again.

Attribute mapping

Send these SAML attributes (email also arrives as the Name ID):

Options on the connection (changeable any time)

These live on the connection card, separate from setup, because the decisions can change later without re-testing:

• Enforce SSO — members on this connection's assigned domains must sign in through the IdP to use this org (details below). Turning it on asks for confirmation and reminds you to keep a break-glass account.
• Enable SAML single logout — send SAML logout to your IdP's SLO endpoint when members sign out.
• Reauthentication cadence (page-level) — how often members must re-verify with your IdP: never / daily / every 3 days / weekly / every 2 weeks.

Enforce SSO (per-organization access)

Enforcement gates access to this organization, never the person's ability to log in:

• Password and Google sign-in still succeed — they just can't open the enforced org. The member's personal workspace (and any other org) stays fully reachable.
• Opening the enforced org shows a "requires SSO" screen with Continue with SSO — one fresh authentication at your IdP (an existing password session is deliberately not enough) and the org opens. The org never disappears from the workspace switcher.
• Enforcement binds to the assigned domain: a member invited with an off-domain email (e.g. a contractor on gmail.com) is not gated.
• Break-glass accounts (added on the SSO page; 2FA is required) may still open the org with a password — your way back in if the IdP has an outage. Keep at least one.

Provider quick-starts

You need three values from each provider: the SSO URL, the Issuer / Entity ID, and the signing certificate.

Okta

Applications → Create App Integration → SAML 2.0. Set Single sign-on URL = our ACS URL, Audience URI = our SP Entity ID, Name ID format = EmailAddress, and add the three attribute statements (email, firstName, lastName). Then copy Okta's Identity Provider Single Sign-On URL, Issuer, and x.509 certificate (from View SAML setup instructions) into our form.

Microsoft Entra ID (Azure AD)

Enterprise applications → New application → Create your own → SAML. Set Reply URL (ACS) and Identifier (Entity ID) to ours; configure claims for email, firstName, lastName. Copy the Login URL, Microsoft Entra Identifier, and the Certificate (Base64) into our form.

Google Workspace

Admin → Apps → Web and mobile apps → Add custom SAML app. Google shows the SSO URL, Entity ID, and Certificate first — copy those into our form. On Service provider details, paste our ACS URL and Entity ID, set Name ID format = EMAIL, map email → Primary email, firstName → First name, lastName → Last name, and turn the app ON for the right OU.

Second-factor strength is your IdP's job — configure MFA / hardware-key requirements there.

Offboarding

SSO provisions; it doesn't deprovision. Connect SCIM so your IdP can push the full lifecycle — deactivating a user there revokes their seat and their API keys here. A SCIM-deactivated user is also refused at the next SSO login.

Troubleshooting

Security

• Routing and enforcement bind to DNS-verified domains only — an org can never capture or gate a domain it hasn't proven it owns.
• Assertions are signature-validated against the certificate you pasted; requests and responses use signed POST bindings.
• The enforcement gate demands a fresh IdP authentication — an existing password or Google session is never silently upgraded to SSO.
• Changing SSO configuration requires a stepped-up (recently re-authenticated) admin session, and every change is written to the organization's audit log.