Single Sign-On (SSO)

SelfDocHub can sign people in through any number of external OpenID Connect providers such as Keycloak, Microsoft Entra ID, Okta or Google Workspace. The provider authenticates the person, including its own password policy and MFA, and SelfDocHub then issues its usual session. Roles, teams, Try-It, exports and the MCP server work unchanged.

Roles: Configuring providers is for admin only. Every user can link and unlink providers on their own Profile page. SSO needs the sso feature in your license (Business and Unlimited tiers). LDAP and SAML are not implemented.

Setting up a provider#

  1. In your identity provider create a confidential OIDC client for the authorization code flow, and add the redirect URI <base_url>/auth/sso/<slug>/callback. The exact URI is shown in the provider form after the first save. To use group rules, make the provider put groups in the ID token.
  2. As an administrator open SSO in the top menu (/sso) and click the plus button. Fill in:
    • SSO name: shown on the login page ("Sign in with "). Unique.
    • Slug: part of the redirect URI. Fixed after creation.
    • Issuer URL, Client ID, Client secret. Test connection loads the issuer's discovery document. The secret is stored encrypted, is write-only and never returned or logged. Leave it empty on edit to keep the current one.
    • Scopes (openid profile email by default), the claim used as login (preferred_username by default) and the claim with groups (groups by default).
    • Allowed email domains and a required group limit who may sign in. Empty means anyone the provider authenticates.
    • Trust the provider's MFA: users skip the local two-factor code.
    • Create users automatically, with a default role and default teams.
  3. Enable the provider. Providers appear on the login page in list order; arrows reorder them.

Disable password sign-in for non-admin users hides the password form and refuses passwords from everyone but administrators. Administrators keep an emergency path at /login?local=1, and the form is always shown when no provider is enabled.

How sign-in works#

Users are recognized by the pair provider + sub claim, never by email or login, so a changed email cannot take over an account. The flow is authorization code with PKCE. The session token never appears in a URL: the callback redirects to the login page with a one-time code that the page exchanges for the session.

For a first-time person, if automatic creation is on, a passwordless user is created with the provider's default role and teams, using the login claim as the login. If that login already belongs to someone else, sign-in is refused ("login taken"). Accounts are never linked automatically: the person signs in the usual way and links the provider from the profile. Failures return to the login page with a message.

Group mappings#

A provider can map identity-provider groups to a role and/or teams. With several matching rules the highest role wins and teams are merged. A rule needs a role or teams, and an admin rule has no teams.

With Recompute roles and teams from groups on every sign-in on, each sign-in recalculates what came from groups: a matched role is applied, a role that came from a group falls back to the default when no group matches, mapped teams are added and teams added earlier for a group the person left are removed. Memberships added by an administrator or taken from the default teams are never touched. With the switch off, groups matter only at creation.

Linking accounts#

On the Profile page (/profile) each enabled provider shows its state with Link and Unlink. An external account can belong to one user, and a user can have one account per provider. The last remaining way to sign in cannot be removed: set a password or link another provider first. Unlinking asks users who have a password to confirm it.

Administrators see each user's sign-in methods in Users and can force-unlink a provider in the user dialog, for example for someone who left. Deleting a provider also unlinks its identities; the UI first shows how many users would be left without a way to sign in.

Audit events#

SSO records audit events such as sso_login_success, sso_login_denied, sso_user_provisioned, sso_link and sso_unlink. They contain metadata only, never tokens or secrets.

Next steps#

Screenshots

Last updated: