Single sign-on
Flux can let people sign in with your organisation’s OpenID Connect identity provider (Keycloak,
Google Workspace, Okta, Authentik and others). Flux supports one provider per instance. Its mode
is set by FLUX_SSO_MODE:
preparekeeps email/password sign-in, sign-up and reset, and lets each existing password account link the provider before cutover (see Moving existing accounts).sso(the default with a provider) is the cutover: email/password sign-in, sign-up and reset are refused by the API and hidden in the browser, and a password-only session no longer continues. Only the provider signs people in. To return to password mode, unset theFLUX_OIDC_*variables and restart.
What it does and does not do
Section titled “What it does and does not do”- Who the person is comes from the provider’s verified ID token: the issuer and the stable
subject (
sub). The same subject is always the same Flux person, even when the provider changes their email or name; Flux updates both on the next sign-in. - The account email is taken only when the provider says it is verified (
email_verified). A sign-in without a verified email is refused. - No account takeover by email. A provider identity is never linked to an existing Flux account
just because the emails match. If the provider’s verified email belongs to a verified Flux account,
or to an account already linked to a provider identity, the sign-in is refused and nothing changes.
If it belongs to an unverified account with no provider link,
prepareoffers link first: sign in to that account and link the provider in Settings → Account, keeping its existing data. After SSO cutover the page points to audited operator recovery instead of password sign-in. Both phases offer claim the address. Claiming releases the address from that account (it becomesunverified-<id>@invalid, its sessions and agent connections end, and an audit row names both accounts). The account’s data stays with it and does not move to the new account. The claim page is open for 15 minutes after the provider sign-in. - Email verification of password accounts. Accounts made before single sign-on are unverified. Once
email is set (
FLUX_SMTP_URL), they receive a verification mail the next time they sign in with their password in password orpreparemode, and admins can find an account by email only when its address is verified. Inpreparemode a new password account still comes only from an invite link (#1471). - The provider decides who joins, Flux decides the rest. Everyone the provider lets in joins the
company as a member on their first sign-in, with no invitation. Groups, roles and domains in the
token are ignored: a person’s company role and their spaces are set in Flux. An account that
existed before it linked the provider joins on its first provider sign-in too. Someone an admin
removes in Flux does not rejoin by signing in again: Settings › Company lists them under
Removed, and Restore lets them back in, in Everyone. Other spaces are added again by hand.
In
ssomode nobody makes an invite link; inpreparemode invites still work, because password accounts are still the way in. - Notification email goes to the account email, a separately verified private address, both, or nowhere, as each person chooses (notifications). When the two are the same mailbox, the person gets one message.
Set it up
Section titled “Set it up”-
Register Flux with your provider as a confidential web application using the authorization-code flow with PKCE and the scopes
openid email profile. The redirect URI ishttps://<your Flux origin>/api/auth/callback/<provider id>. Flux prints the exact value when the API starts with single sign-on on (Single sign-on is on, fieldredirectUri):Terminal window docker compose --env-file docker/release.env --env-file docker/.env -p "$(sed -n 's/^FLUX_PROJECT=//p' docker/.env)" \-f docker/compose.yaml logs --no-log-prefix api | grep 'Single sign-on is on'The provider id is derived from the issuer URL, so changing the issuer creates a new identity namespace. Keep the issuer stable during normal operation; if it must change, use the explicit
--old-issueroperator recovery procedure below before people sign in at the new issuer. -
Save the client secret in a file readable only by you, for example
/etc/flux/oidc_client_secret. -
Add to
docker/.env(or the release’s.env):Terminal window FLUX_OIDC_ISSUER=https://id.example.org/realms/acmeFLUX_OIDC_CLIENT_ID=fluxFLUX_OIDC_CLIENT_SECRET_HOST_FILE=/etc/flux/oidc_client_secretFLUX_OIDC_LABEL=Acme loginThe issuer must be
httpsand must be the provider’s exact issuer (its/.well-known/openid-configurationis read from there). Set issuer and client id together; with neither, single sign-on stays off.FLUX_OIDC_LABELnames the button (“Sign in with Acme login”); it defaults to “single sign-on”../fluxmounts the file into the API container; apply the settings with./flux up. -
Optional: confirmation age.
FLUX_OIDC_CONFIRMATION_MAX_AGE(default7d; whole hours or days from1hto30d, such as12h) is how long the provider’s last confirmation of a person keeps their access. It starts at each sign-in through the provider. After it, that person’s provider browser sessions return to sign-in, their MCP requests get 401invalid_token, and the refresh grant getsinvalid_grantuntil they sign in through the provider again; the client then authorizes again and/connect-agentoffers the connection it held. Without the standing check, this age is the offboarding bound: a person disabled at the provider keeps access at most this long. People with only a Flux password cannot sign in while the provider is set (see above). -
Restart:
./flux up. The sign-in page shows “Sign in with Acme login” once the API reads the provider’s discovery document.
The API reads discovery when it starts. If the provider is unreachable then, single sign-on fails until the next restart; password sign-in stays closed in the meantime.
Standing check
Section titled “Standing check”Flux asks the provider for offline_access at sign-in and keeps the refresh token it returns,
sealed with a key derived from FLUX_AUTH_SECRET, in auth_idp_standing.
The sign-in takes two steps. The person signs
in with openid email profile. Flux then sends the browser back to the provider once more, silently,
with prompt=none and scope=openid offline_access, to the same redirect URI. You register nothing
new. The person sees only a second redirect.
The reason is Keycloak 26.1 and later: when offline_access is the first request of a new Keycloak
session, Keycloak deletes the browser session at the code exchange . The provider
then never sends a back-channel logout to Flux, and other applications lose single sign-on.
-
A refused silent step. If the step answers
login_requiredor another error, the sign-in is refused like a missing refresh token, and the API logs the provider’s answer. A provider session thatprompt=nonecannot reuse causes this, for example when the provider’s own cookies are blocked. -
When Flux revokes a stored token. Flux revokes the token it replaces only when no live Flux browser session came from that token’s provider session (
sid). Revoking a Keycloak offline token also takes Flux out of that browser session’s logout. -
Tokens Flux does not revoke end at the provider’s offline idle limit (Keycloak: 30 days). Until then, Keycloak lists them as offline sessions of the Flux client. Every
FLUX_OIDC_STANDING_INTERVAL_SECONDS(default 900) the API uses that token for each person with a live session or agent connection. If the provider answersinvalid_grant(a disabled user, a removed offline session), the person is in sign-in required: their browser sessions end, MCP requests answer401 invalid_tokenwith “Sign in again with” and your label, the refresh grant answersinvalid_grant, and automation that acts for them stops. Nothing is revoked. A network error, timeout, 5xx orinvalid_clientchanges nothing. -
Restoring access. Checks continue for a suspended person. When the provider honours the token again (a re-enabled Keycloak user), the next check clears the state; their local clients’ connections work again, and they sign in again in the browser.
-
The provider must return a refresh token. Grant the Flux client the
refresh_tokengrant and let the people useoffline_access(Keycloak: theoffline_accessrole; Okta: the Refresh Token grant). A sign-in that returns none is refused with a message, and the API logsThe identity provider returned no refresh token. For a provider that cannot, setFLUX_OIDC_STANDING=off: then only the confirmation age and back-channel logout end access. -
Backups and restores.
./flux backupkeeps the table’s rows out of the archive. After a restore, every person who signed in through the provider is in sign-in required until they sign in again. -
Back-channel logout. In the provider’s client settings, set the Backchannel logout URL to
<FLUX_PUBLIC_ORIGIN>/api/v1/identity/oidc/<provider id>/backchannel-logout(the id is in theSingle sign-on is onlog line and in the redirect URI) and require the session id. Flux verifies the signed logout token (signature from the provider’s keys, issuer, audience, times, the logout event, nononce, and ajtiit has not seen), ends the browser sessions created from that provider session (or all of the person’s sessions when onlysubis sent), and asks for an immediate standing check. A plain logout does not stop agents; with Keycloak’s Backchannel logout revoke offline sessions on, Flux also revokes the person’s MCP refresh tokens and its own stored provider token, so agents must be authorized again. Flux answers 200, or 400 for a refused token, withCache-Control: no-store; an unknown session id is answered 200. -
Only the stored state is read per request; an unreachable provider adds no latency to MCP calls.
Tested with
Section titled “Tested with”./scripts/check_oidc.sh runs a pinned, disposable Keycloak and a deterministic mock provider in
Docker and drives the real browser flow: sign-in, a stable subject across email changes, refused
unverified, colliding, replayed, forged, wrong-nonce, wrong-key, wrong-issuer and wrong-audience
tokens, sessions across an API restart, sign-out, the confirmation age at the browser, MCP and the
refresh grant, and notification mail. With FLUX_OIDC_CLOSEOUT=1 it also signs Codex and Claude Code
in as MCP clients through Keycloak. It uses its own Compose project and ports
(FLUX_OIDC_TEST_PORT, default 18095) and removes everything afterwards.
Not covered: SAML, SCIM provisioning, several providers at once, and a production provider’s own policies (MFA, conditional access), which stay the provider’s responsibility.
Agents (MCP clients) with single sign-on
Section titled “Agents (MCP clients) with single sign-on”The page
an agent client opens for authorization (/login, for example from claude mcp login) shows
Sign in with and your FLUX_OIDC_LABEL, the only sign-in offered while the provider is set. Flux keeps the signed authorization request through
the provider round trip and continues to the connection choice and consent afterwards; the client only
ever receives Flux’s own code and tokens, and an access or ID token issued by the provider is refused at
/mcp. If the provider step is cancelled or fails, the page returns to /login with the same request
and a message. If the provider’s discovery document cannot be read, the button is disabled and says
<label> is not reachable right now. Flux keeps retrying a provider that was unavailable at startup.
The same signed login page enables sign-in when it recovers; no API restart or page reload is needed.
Pre-registered Codex clients: register the callback that Codex displays. It is the stable
http://127.0.0.1/callback when the server advertises the issuer response parameter, as Flux does.
Moving existing accounts
Section titled “Moving existing accounts”Accounts made with a password before the provider existed have no provider identity, so they cannot sign in once the cutover is on. Move them first, in this order:
- Set
FLUX_OIDC_*andFLUX_SSO_MODE=prepare, then restart. Password sign-in keeps working. - Each person signs in with their password, opens Settings, and selects Link …. They complete one provider sign-in as the same person. Flux links that provider identity to their existing account: the account ID, data and memberships stay. Flux matches nothing by email. An identity that another account already holds, or an account already linked to another identity, is refused with the reason shown in Settings, and nothing changes. A link lasts 10 minutes and works once.
- When everyone who needs access has linked, set
FLUX_SSO_MODE=sso(or remove the setting) and restart. At startup the log says how many password-only accounts are still left. They cannot sign in until they are moved; there is no ordinary password fallback.
Accounts that cannot link (for example, the provider account was lost): the operator re-keys them with
./flux identity link <userId> --subject <provider subject> --reason "<why>". It names the account by its Flux id,
never by an address, and refuses a subject another account holds. In SSO-only mode it refuses unless
--allow-sso is given. A re-key writes an audit row (auth_identity_audit) with the actor, the reason and the
old/new subjects and issuer values. For a changed issuer, pass the exact former issuer explicitly with
--old-issuer <issuer URL>; Flux checks that issuer’s derived provider id against the sole provider mapping on
that Flux account before replacing it with the currently configured provider identity. Missing or ambiguous
mappings are refused, and historical audit rows whose issuer was never recorded remain unknown. A successful
re-key ends the account’s sessions and old MCP authority/refresh credentials; its Flux data stays where it is.
Removing a sign-in is an operator recovery action, not a Settings action. Settings never removes the provider
sign-in, in any mode. The host operator removes it with ./flux identity unlink <userId> --reason "<why>", which is
refused when it is the account’s last way in: always in SSO-only mode, and in prepare mode when the account has no
password. A removal ends the sessions that signed in through it and the account’s MCP authority, keeps the account’s
Flux data, and writes an audit row.
Provider notes
Section titled “Provider notes”Claim rules. Generic OpenID Connect providers use the verified email_verified claim. Microsoft Entra ID
requires the token’s tenant (tid) to match its issuer, and an address counts as verified only with the
xms_edov (email domain owner verified) claim. Google requires email_verified. These rules are unit-tested against
documented claim shapes. Real Entra and Google tenants have not been tested; their compatibility stays unverified
until a recorded integration run exists.