Repository navigation
feat(auth): add break-glass login links for OIDC mode - #449
Merged
Merged
Conversation
`fanout login-link --break-glass <email>` issues a one-time link for an active administrator when the identity provider is unavailable. In OIDC mode `/api/auth/link/verify` accepts only those links, re-checks the account is still an active administrator, and writes distinct audit events for issuing and redeeming. A break-glass link is a distinct `verifications.purpose`, so ordinary links can never match it and no migration is needed. OIDC startup still does not require FANOUT_AUTH_CODE_SECRET; issuing fails with an error naming the variable and the route stays disabled until it is set, and the code store refuses to hash credentials with an empty secret. Closes #444
Warn at startup when OIDC mode has a FANOUT_AUTH_CODE_SECRET too short for break-glass links, without failing startup or logging the value. Make the audit write mandatory for break-glass redemption: when it fails, destroy the session and return 500. Ordinary links and OIDC login keep their best-effort audit. Give suspended or missing break-glass redemptions their own audit reason, and document that the verify route's per-client rate limit needs FANOUT_TRUSTED_PROXY_CIDRS behind a proxy.
Write the redemption audit event after eligibility checks and link consumption but before establishing a session, so an audit failure returns 500 with no session ever created. This removes the destroy path, which could still commit a session if the destroy itself failed.
vishr
enabled auto-merge (squash)
November 8, 2026 17:27
…-login # Conflicts: # internal/api/auth_test.go # internal/config/config_test.go
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #444
What changed
fanout login-link --break-glass <email>issues a one-time, 15-minute link for an active administrator in OIDC mode. It refuses other roles, suspended users, and local mode. The flag works on either side of the email./api/auth/link/verifyaccepts only those links. An ordinary login link is refused and not consumed. The route re-checks at redemption that the account is still an active administrator, so a link issued before a demotion or suspension no longer works.login_link.break_glass_issuedand redeeming writeslogin_link.break_glass_redeemed, separate from the existinglogin_link.*events. Suspended or missing accounts get their ownlogin.failedreason,suspended_or_missing_break_glass_user.FANOUT_AUTH_CODE_SECRETunder 32 characters. It names the setting, never the value, and does not fail startup.FANOUT_TRUSTED_PROXY_CIDRSmust be set behind a proxy.Decisions to review
verifications.purposevalue,break_glass_login_link. The purpose is free text with no CHECK constraint, so there is no migration.GetUnusedLoginLinknow takes the purpose as a parameter, which keeps the two link kinds from matching each other. A break-glass link is also refused in local mode if the mode changes during its lifetime.FANOUT_AUTH_CODE_SECRETstays optional at OIDC startup, so existing installs keep booting. A missing or shorter-than-32-character value makes--break-glassfail with an error naming the variable. In that state the route returns the same 404 as before, with no audit write and no rate-limit change.CodeStorealso refuses to create or verify any credential with an empty secret.login.failedaudit event rather than 404, so an operator with an expired link sees a useful message. A valid link for a non-administrator gets 403.RegisterOIDCRoutesstill runs provider discovery at startup and the server exits if it fails, so break-glass needs a server that is already running. The docs describe that behaviour. Open issue Start without the OIDC provider and retry discovery #443 tracks starting without the provider; the doc paragraphs should be removed when it lands.Verification
Run on the final head:
bash scripts/with-duckdb.sh go test ./internal/auth ./internal/config ./internal/api ./cmd/fanout ./cmd/fanout-docgen -count=1: passed.bash scripts/with-duckdb.sh go test -race ./internal/api ./internal/config -count=1: passed.just check(the full gate): passed on this head.TestBreakGlassRedemptionFailsClosedWhenAuditWriteFailsfail.Run on the first commit and not repeated:
-raceon./internal/auth ./cmd/fanout, which passed.just docs-generateandjust docs-generate-checkalso ran then; the follow-up did not change the configuration schema, andjust checkincludes the generate check.New tests cover: issuing for an active administrator; refusing viewer, operator, suspended administrator, empty secret, short secret, and local mode; no-flag behaviour in OIDC mode; single-use redemption and its audit events; an ordinary link refused in OIDC mode without being consumed; non-administrator, suspended, and missing users refused at redemption with their audit reasons; audit failure returning 500 with no session cookie, no sessions row, and no login timestamp; ordinary links still succeeding when their audit write fails; the startup warning; the route staying disabled without a usable secret; a break-glass link refused in local mode; and empty-secret refusal in
CodeStore.Not run: the full
just test-race(machine heavily loaded), an end-to-end test against a real identity provider, and a browser click-through of a break-glass link. I readui/host/src/auth.tsxand it redeemslogin_tokenbefore rendering the OIDC sign-in page, so no UI change was made, but that path was not exercised.