Federated sign-in over OIDC, as a second door beside the password form — never a replacement for it.
Turning it on
Setting OIDC_ISSUER_URL is the on/off switch. Left empty, no discovery request is ever made and no
button renders on /login, though the SSO routes stay registered (GET /api/auth/oidc/login answers
404, and the callback redirects to /login?oidc_error=not_configured). Set it, and discovery is
fetched once, on the first sign-in attempt, and cached.
| Variable | Default | Notes |
|---|---|---|
OIDC_ISSUER_URL |
– | The provider’s issuer URL. On/off switch for the whole feature |
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET |
– | Issued by the provider. OIDC_CLIENT_SECRET is a process secret like ADMIN_TOKEN — read from the environment, never written to the database, so no backup or dump ever carries it |
OIDC_REDIRECT_URI |
computed | Optional. The callback URL registered with the provider, e.g. https://docs.example.com/api/auth/oidc/callback. Left unset it is <base>/api/auth/oidc/callback, where <base> is PUBLIC_BASE_URL or, without it, the request’s own scheme and host. Set it when the provider needs an exact match the request’s host cannot be trusted to produce |
OIDC_SCOPES |
openid profile email |
Space-separated scopes requested at the provider |
OIDC_BUTTON_LABEL |
Single sign-on |
Text on the /login SSO button |
OIDC_AUTO_PROVISION |
0 |
1 lets a first successful provider sign-in create an account here on its own. Off by default: an unmapped provider identity is refused rather than silently handed an account |
OIDC_DEFAULT_ROLE |
member |
Role a provisioned account gets. admin or member only — never root |
There is nothing to configure from the dashboard for the provider itself; these variables are set by the operator in the instance’s environment. See Configuration for how settings are applied.
Signing in
A federated sign-in is always matched to an account by the provider’s sub claim, never its e-mail
claim — an e-mail is exactly what a misconfigured or compromised provider could forge into reaching a
different local account. Changing your e-mail at the provider does not disconnect you and cannot
accidentally connect you to someone else’s account.
Whether a new account can be created this way at all is the operator’s choice
(OIDC_AUTO_PROVISION), off by default. With it off, signing in through the provider is refused unless
the provider identity is already linked to an account. An account an admin created is not matched by
username or e-mail: its owner signs in once with the password and links the identity themselves (below). Turn it on and a first
successful sign-in mints an account with OIDC_DEFAULT_ROLE.
Once signed in, a federated account is governed by the same role table as any other account — nothing about what you can reach depends on how you signed in — and a provider outage never blocks local password sign-in. The two doors do not depend on each other.
Linking or unlinking your own account
Once signed in — by password or by the provider — every non-root account can connect or disconnect its
own federated identity on the API tokens page (#/~tokens), under the Single sign-on heading. Connecting starts the
identical provider redirect the login button uses, but links the identity it comes back with to the
current session instead of signing in to whichever account already owns it. Linking a provider
identity that is already linked to a different account is refused, not merged — each identity belongs to
exactly one account.
Unlinking is self-service and revokes the account’s standing credentials in the same request: every
session and every API token that account holds is invalidated the moment the identity is removed —
including the session making the request — because unlinking is also what clears the way for a later
promotion to root, and nothing opened while the account was still provably tied to an external identity
provider should outlive that link. The same transaction revokes the account’s MCP OAuth credentials —
every access and refresh token it was issued for /mcp/<project> — so an MCP client signed in as that
account gets 401 on its next request and has to authorize again; other accounts’ credentials are
untouched. The audit event of the unlink records how many were revoked, as detail.revokedMcpCredentials.
Sign back in locally, since the link is gone, to get a working session again.
If the account has no local password and this link is its only way to sign in, unlinking is refused
(409 last_sign_in_method) — nothing removed, nothing revoked — until an admin sets a password for it
first with POST /api/users/:id/password.
root stays local, always
root cannot link a provider identity in the first place — the control never appears for it in the
dashboard, and the API refuses the attempt directly (403 root_local_only). The reverse direction is
guarded too: granting root to an account that still has a linked identity is refused
(409 root_requires_unlink), on the Users page and at the API, checked ahead of the write — so the
account’s role never actually becomes root while the link exists. As a second line of defence, a
session’s role and sign-in method are re-read on every request; if an account somehow did reach root
while still linked, a session opened over SSO for it would be signed out on its very next request rather
than allowed to act as root. Only after unlinking can another root account grant the root role.
This is why the one account this product cannot recreate from a provider claim — root — never signs in
over SSO.
Groups grant project memberships
With OIDC_GROUPS_CLAIM set to the top-level claim of the ID token that lists a person’s groups (for example
groups), those groups can grant project memberships. An administrator maps a group name to a project and a role
(viewer or editor) under Users → SSO group mappings, or through GET/POST /api/oidc/group-mappings and
DELETE /api/oidc/group-mappings/:id. Group names are matched exactly, capitals included, and a group never changes an
instance role: nobody becomes admin or root through one. Unset, nothing here runs and sign-in is unchanged. The
claim is read from the ID token only, and a nested claim path is not supported. A provider that needs a scope to emit
the claim gets it through OIDC_SCOPES.
At each SSO sign-in of a member account:
- The account’s group-granted memberships become exactly the projects its groups map to; where two groups map the same project, the higher role applies.
- A membership added by hand for the same project wins and is never changed or removed by a group.
- A person who has left a group loses the membership at their next sign-in, not before. To cut access at once, disable the account.
adminandrootaccounts are skipped: they reach every project already.
While the setting is on, the members API answers 409 membership_managed_by_group for a group-granted row, because the
next sign-in would put it back. A group-granted membership is also removed when its mapping is deleted, when its account
unlinks SSO, and when a linked account signs in with its password. Turning the setting off removes nothing.
A claim that is missing, null, [] or {} means no groups, and sign-in goes on. A claim that cannot be read — Microsoft
Entra’s overage marker (_claim_names.groups), anything but a list of strings, more than 1 000 entries or a name over 256
characters — stops a member’s sign-in with groups_unavailable and changes nothing. Every membership a sign-in changes is
one audit event. With the Helm chart the setting is config.oidcGroupsClaim.
The Admin API
Linking and unlinking are also two ordinary endpoints, callable from a script by a signed-in caller’s own session — see Admin API.