Single Sign-On (SSO)

What it does

With SSO configured, people at your company domain sign in to the portal through your identity provider instead of an emailed link. transmute uses OpenID Connect (authorization code flow with PKCE). Your provider decides who may sign in — MFA, device posture and deprovisioning all follow your provider's policy.

SSO covers portal sign-in only. API calls still use API keys or OAuth client credentials.

Requirements

• You are the workspace owner.
• Your own sign-in email is on your company domain (for example you@acme.com). SSO binds to that domain; public mailbox domains (gmail.com, outlook.com and similar) can't be used. A domain can belong to one workspace only.
• An OpenID Connect provider that publishes a discovery document over HTTPS and signs ID tokens with RS256 or ES256.

Set it up

1. In the portal, open SSO (owners only) and copy the redirect URI shown there.
2. At your identity provider, create a confidential web application (OpenID Connect, authorization code flow) with that redirect URI and the openid and email scopes. Note its client ID and client secret.
   • Okta: Applications → Create App Integration → OIDC → Web Application. Issuer: https://<your-org>.okta.com (or your custom authorization server URL).
   • Microsoft Entra ID: App registrations → New registration → Web redirect URI; create a client secret. Issuer: https://login.microsoftonline.com/<tenant-id>/v2.0.
   • Google Workspace: Google Cloud console → Credentials → OAuth client ID → Web application. Issuer: https://accounts.google.com.
   • Keycloak: Clients → Create → OpenID Connect, client authentication on. Issuer: https://<host>/realms/<realm>.
3. Back in transmute, enter the issuer URL, client ID and client secret, then Save and Test connection. The test fetches your provider's discovery document and signing keys without signing anyone in.
4. Sign out and use Continue with SSO on the sign-in page to try it.

The client secret is write-only: it is stored encrypted and never shown again. To change it, enter a new one and save; leave the field empty to keep the stored secret.

Options

How sign-in works

• On the sign-in page, a person enters their work email and chooses Continue with SSO; transmute sends them to your provider and back.
• transmute checks the provider's signed ID token (issuer, audience, expiry and a one-time nonce) and requires its email to be on your verified domain. If the provider says the email is unverified, sign-in is refused.
• Every login attempt is single-use and bound to the browser that started it; a replayed or forwarded callback is refused.
• A successful SSO sign-in creates the same portal session as an email link.
• transmute never stores your provider's access or refresh tokens.

Troubleshooting

• "Single sign-on isn't set up for this email domain" — the email's domain has no SSO configuration. Check the spelling, or use an email link.
• "Single sign-on didn't complete" — the provider refused the sign-in, the attempt expired (10 minutes), the email is outside your domain, or (with account creation off) the person has no account yet. Invite them from Team, or turn on account creation.
• Test connection fails — discovery_unreachable: the issuer URL is wrong or not reachable from the internet; issuer_mismatch: the issuer you entered differs from the one your provider publishes (watch for a trailing slash); no_usable_keys: the provider publishes no RS256/ES256 signing keys; insecure_endpoint: an endpoint is not public HTTPS.

Not yet available

SCIM provisioning and SAML are not supported yet. Domain verification by DNS record is planned; today the domain is taken from the owner's own sign-in email.