# 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 <name>"). 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

- [Users and Two-Factor Auth](/documentation/users-and-two-factor)
- [Teams](/documentation/teams)
- [Security and Audit](/documentation/audit-and-security)

---
Source: https://selfdochub.com/documentation/single-sign-on
