Single sign-on (OIDC)
Let your team sign in through your identity provider with OpenID Connect — setup, domain routing, provisioning rules and known limits.
Organizations on the Enterprise plan can connect one OpenID Connect identity
provider (Okta, Azure AD / Entra ID, Google Workspace, Keycloak, Auth0, …). On
other plans the settings page is hidden and the procedures answer
FEATURE_NOT_AVAILABLE.
Setup
Only the organization owner can configure SSO: Organization settings → SSO.
| Field | Meaning |
|---|---|
| Issuer | The IdP issuer URL; discovery is read from /.well-known/openid-configuration |
| Discovery endpoint | Optional override of the discovery URL |
| Client ID / Client secret | From the application you registered at the IdP |
| Domain | Your work e-mail domain, e.g. acme.com |
| Scopes | Optional; defaults to the standard OIDC scopes |
Register this redirect URI at your IdP:
https://<your-console-host>/api/auth/sso/callback/<organization-slug>The provider id is the organization slug, which is why it appears in the callback.
After saving, the console shows the secret only as ***; leave it untouched to
keep it, type a new one to replace it.
Domains
- One provider per organization, one domain per provider.
- Consumer mailbox domains (
gmail.com,outlook.com,yahoo.com,icloud.com,proton.me,mail.ru, …) are refused: claiming one would route every such user into your organization. - A domain already claimed by another organization is refused.
- The organization slug becomes the provider id, so a slug that collides with a
sign-in method (
google,github,credential,email,sso,admin, …) is refused (SSO_PROVIDER_ID_RESERVED). Change the slug first.
Verifying the domain
Sign-in through the provider stays off until you prove that you own the domain in DNS. Owning one mailbox at the domain is not enough: a verified provider is trusted to sign in existing users with a matching e-mail.
-
On the SSO page, start the domain verification. The console shows a TXT record, valid for 7 days:
_aacsearch-challenge.<your-domain> TXT "aacsearch-domain-verification=<token>" -
Publish it at your DNS provider.
-
Press Verify. When the record is visible (
dig +short TXT _aacsearch-challenge.<your-domain>), the domain is marked verified and single sign-on is active. If DNS has not propagated yet you getSSO_DOMAIN_VERIFICATION_FAILED; wait and retry. An expired record is replaced by requesting verification again.
Changing the provider's domain resets the verification: repeat the steps for the new domain. Only the owner can verify.
Signing in
On the login page users choose Continue with SSO and type their work e-mail (or just the domain). They are redirected to your IdP and back.
A user who signs in through your provider becomes a member of your
organization — never admin or owner, whatever the IdP claims. Promote people
in Members as usual.
Removing SSO
Delete the provider on the same page (owner only). Users can no longer sign in through it; membership is managed in Members as usual.
Known limits
- SAML is not supported, only OIDC.
- The client secret is encrypted at rest (AES-256-GCM) and is decrypted only in memory for the token exchange. Rotate it at the IdP if you suspect a leak.
- A plan downgrade switches SSO sign-in off at once (
SSO_NOT_AVAILABLE). The provider is kept, so upgrading back to Enterprise restores it without a new setup. - At sign-in the auth plugin calls the IdP's token, userinfo and JWKS endpoints itself. They are checked against internal addresses when the provider is saved, not again at sign-in.