Skip to content

feat(auth): add break-glass login links for OIDC mode - #449

Merged
vishr merged 5 commits into
mainfrom
feat/oidc-break-glass-login
Nov 8, 2026
Merged

vishr merged 5 commits into
mainfrom
feat/oidc-break-glass-login

Conversation

@vishr

@vishr vishr commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

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.
  • In OIDC mode, /api/auth/link/verify accepts 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.
  • Issuing writes login_link.break_glass_issued and redeeming writes login_link.break_glass_redeemed, separate from the existing login_link.* events. Suspended or missing accounts get their own login.failed reason, suspended_or_missing_break_glass_user.
  • The break-glass redemption audit is mandatory. It is written after the eligibility checks and link consumption, before any session is established. If it fails, the request returns 500 and no session is created. Ordinary links and OIDC login keep their best-effort audit.
  • Startup logs a warning when OIDC mode has a non-empty FANOUT_AUTH_CODE_SECRET under 32 characters. It names the setting, never the value, and does not fail startup.
  • Without the flag, the CLI refuses OIDC mode with the same error as before.
  • CLI reference, authentication docs, README, and generated configuration docs are updated. The recovery docs also say the verify route is rate limited per client address, so FANOUT_TRUSTED_PROXY_CIDRS must be set behind a proxy.

Decisions to review

  • How a link records break-glass: a new verifications.purpose value, break_glass_login_link. The purpose is free text with no CHECK constraint, so there is no migration. GetUnusedLoginLink now 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.
  • Secret compatibility: FANOUT_AUTH_CODE_SECRET stays optional at OIDC startup, so existing installs keep booting. A missing or shorter-than-32-character value makes --break-glass fail 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. CodeStore also refuses to create or verify any credential with an empty secret.
  • Status codes: with a usable secret in OIDC mode, an invalid or ordinary link now gets 401 and a login.failed audit event rather than 404, so an operator with an expired link sees a useful message. A valid link for a non-administrator gets 403.
  • Audit before session: a session-creation failure after a successful audit leaves an audited redemption with no login. The link is spent either way, so the operator issues a new one.
  • Discovery at startup: in this PR, RegisterOIDCRoutes still 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.
  • Pre-push just check (the full gate): passed on this head.
  • Mutation check: moving session establishment ahead of the mandatory audit makes TestBreakGlassRedemptionFailsClosedWhenAuditWriteFails fail.

Run on the first commit and not repeated: -race on ./internal/auth ./cmd/fanout, which passed. just docs-generate and just docs-generate-check also ran then; the follow-up did not change the configuration schema, and just check includes 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 read ui/host/src/auth.tsx and it redeems login_token before rendering the OIDC sign-in page, so no UI change was made, but that path was not exercised.

vishr added 3 commits November 8, 2026 08:22
`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
vishr enabled auto-merge (squash) November 8, 2026 17:27
@vishr
vishr merged commit 7572d3f into main Nov 8, 2026
19 checks passed
@vishr
vishr deleted the feat/oidc-break-glass-login branch November 8, 2026 18:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Break-glass login link in OIDC mode

1 participant