Single Sign-On

Single sign-on (SSO) lets the members of an organization sign in with their company identity provider (IdP) — Microsoft Entra ID, Okta, Google Workspace, or any provider that speaks SAML 2.0 or OpenID Connect — instead of a portal password. Each organization registers its own providers, and each provider is tied to one or more email domains: the domain of your work email decides which provider signs you in.

Enable SSO

SSO is off by default. Turning it on is a deployment setting, not something a user or organization can do:

NEXT_PUBLIC_AUTH_SSO=true

With the flag on (at build time and at run time), the sign-in page shows a Continue with SSO block and organization settings gain a Single Sign-On page. With the flag off, the sign-in block is hidden, the Single Sign-On settings page only shows SSO is disabled on this deployment, and the SSO endpoints are not registered. The remaining DOCK_SSO_* settings (default role, domain verification, provider limit) are documented in config/env/sso.env.example.

DOCK_SSO_DOMAIN_VERIFICATION defaults to true. It is what stops someone from registering a provider for a domain they do not own and signing in as its users. Only switch it off for local experiments.

Sign in with SSO

1. Open the sign-in page and find Continue with SSO under Or continue with.
2. Enter your work email and click Continue with SSO.
3. You are redirected to your identity provider. Sign in there (including any second factor your company requires).
4. You come back to the portal signed in and land on the dashboard.

Alternatively, an administrator can share a deep link /auth/sign-in?sso=<providerId>. It shows a single Continue with your organization's SSO button and skips the email step.

On the first SSO sign-in a portal account is created automatically, unless the deployment disables implicit sign-up. If the provider's email domain is verified and matches exactly one organization, the user is added to that organization with the role set by DOCK_SSO_PROVISION_DEFAULT_ROLE (member by default). Users who are already members keep their existing role.

Common messages:

• We could not find an SSO provider for that email — no provider is registered for that domain, or the address is misspelled.
• This provider's domain has not been verified yet — the organization admin must complete domain verification (below) before anyone can sign in through it.

Set up SSO for your organization

You need the organization's update permission (Owner or Admin by default). Other members can open the page but see a Read-only notice.

1. Switch to the organization and open Settings → Single Sign-On.
2. Click Add provider and pick the OpenID Connect or SAML 2.0 tab.
3. Fill in the form:
   • Provider ID — a lowercase slug such as acme-entra. It appears in URLs and cannot be changed later.
   • Email domains — the domains this provider signs in, comma-separated (acme.com, acme.co.uk).
   • OpenID Connect: Issuer URL, Client ID, Client secret; optionally a discovery endpoint, scopes (openid email profile recommended), PKCE, or manually entered endpoints.
   • SAML 2.0: the IdP sign-in URL, IdP entity ID and signing certificate — or paste the IdP metadata XML and the three are read from it; optional attribute mapping for email and display name.
4. Click Register provider. The dialog then shows Values for your identity provider: the redirect URI (OIDC) or ACS URL, SP entity ID and SP metadata URL (SAML). Click a value to copy it and paste it into the IdP application.
5. Complete Domain verification (next section) and click Done.

The provider now appears in the Identity providers table with its type, domains and status: Verification pending, Verified, or Active when domain verification is disabled on the deployment. Use Setup details to see the IdP values again, and Remove to delete a provider (existing user accounts are kept; members of its domains can no longer sign in through it).

Step-by-step instructions for Entra ID, Okta and Google Workspace, plus a declarative providers.json and the sso:sync CLI for reproducible environments, are in config/sso/README.md.

Domain verification

A provider cannot sign anyone in until the organization proves it owns each listed email domain:

1. In the provider dialog (right after registration, or via Setup details later) click Get verification token.
2. For every domain, create a DNS TXT record with the shown TXT record name — _better-auth-token-<providerId>.<domain> — and the shown TXT record value. The token is valid for 7 days; request a new one if it expires.
3. Once DNS has propagated, click Verify now. On success the status becomes Verified and members with a matching email domain can sign in.

Why verification matters. Verification is the trust boundary: it ties a provider to a domain the organization controls. It also gates membership provisioning — only verified domains add users to the organization automatically.

Good to know

• The settings page cannot edit a registered provider: remove it and register it again, or apply changes with the sso:sync CLI. Even then, identity settings (issuer, client ID, IdP entity ID, certificate) are refused once users have signed in through the provider; register a new provider ID instead.
• Provider IDs that clash with a social sign-in provider configured on the portal (for example google) are rejected as reserved.
• OIDC providers must be reachable on a public hostname; local addresses are refused. SAML has no such restriction.
• Secrets never leave the server: the settings page masks client IDs and never shows secrets or certificates.
• Architecture, security notes and testing tips: modules/sso/README.md.