Claude Fable 5
13f0311d8e
Some checks failed
CI / Lint, typecheck, test (pull_request) Successful in 6m55s
CI / Build container images (pull_request) Successful in 4m43s
CI / Auth e2e pack (pull_request) Successful in 9m13s
CI / Import/export fidelity gate (pull_request) Successful in 1m4s
CD / Deploy to Test (push) Blocked by required conditions
CD / Smoke tests against Test (push) Blocked by required conditions
CD / Promote to Int (push) Blocked by required conditions
CI / Auth e2e pack (push) Blocked by required conditions
CI / Import/export fidelity gate (push) Blocked by required conditions
CI / Build container images (push) Blocked by required conditions
CI / Lint, typecheck, test (push) Has been cancelled
CD / Build and push images (push) Has been cancelled
The deploy-level realization of auth.local.enabled (ADR 0021): FALSE answers 404 on every local credential flow — login, signup, e-mail verification, resend, password forgot/reset/change — enforced centrally in the auth guard via the @LocalCredentialFlow() marker before any session or CSRF logic runs. Deploy-level on purpose: a compromised Site Admin cannot reopen the local path, so the runtime-flip residual risk from ADR 0021 does not materialize (R-02 closed in the risk list). An enumeration fence fails when an auth route is neither marked nor on the reviewed allowlist, so a new credential flow cannot ship unswitched. Stated decisions, each tested: sessions/logout keep working for externally authenticated users; PAT and feed-token issuance stays available (API authorization under its own switches, not interactive sign-in). Bootstrap: complete setup (or SETUP_ADMIN_* pre-seed) before flipping; the api warns at boot when local auth is off with neither OIDC nor proxy auth configured. GET /auth/methods reports local:false and the login page hides the local form and credential links. Hardening guide: the planned auth.local.enabled row moves from 1.3 into the live deploy table with the bootstrap ordering, and the verification checklist gains the login-404 probe. Refs #216. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8
126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
# ADR 0021: External authentication via OIDC; local passwords optional
|
|
|
|
- Status: proposed
|
|
- Date: 2026-07-29
|
|
|
|
## Context
|
|
|
|
ADR 0007 established sessions and identities with OIDC in mind:
|
|
`UserIdentity.provider` is documented as `"password"` today and
|
|
`"oidc:<issuer>"` later, with `@@unique([provider, subject])` already in
|
|
place. No OIDC code exists — the readiness is structural only.
|
|
|
|
Authentication is a security base function under §52 VSA (ADR 0019), so it
|
|
belongs to the operator's platform. An authority environment additionally
|
|
brings its own account lifecycle: joiners, movers and leavers are managed
|
|
in the IdP, and a second account store inside the application would drift
|
|
from it.
|
|
|
|
Some environments terminate authentication at the perimeter instead and
|
|
expect the application to trust a header or a client certificate.
|
|
|
|
## Decision
|
|
|
|
1. **OIDC Authorization Code with PKCE is the primary path**, configured by
|
|
discovery, validated against JWKS. Keycloak is the reference IdP we
|
|
verify against; nothing in the implementation is Keycloak-specific.
|
|
2. **Identities use the existing slot**: `provider = "oidc:<issuer>"`,
|
|
`subject` from the token. Linking an OIDC identity to an existing local
|
|
user follows an explicit, documented rule — never silently by e-mail
|
|
address, which would be an account-takeover path.
|
|
3. **Local authentication is switchable off in full**, via
|
|
`auth.local.enabled = false`. "In full" means every credential-issuing
|
|
flow: password login, self-service signup, password reset,
|
|
verification-as-login, and the token flows (PAT, feed tokens). A
|
|
half-closed local path makes the operating concept untrue, which is
|
|
worse than not closing it.
|
|
4. **Proxy header and mTLS are a supported alternative path, off by
|
|
default.** When enabled they require an allowlist of trusted peers; a
|
|
request carrying the header from an untrusted peer is rejected and
|
|
audited. The trust boundary is stated explicitly in the security
|
|
documentation.
|
|
5. **Claims map onto the existing permission model** declaratively, and
|
|
mapped grants are written through the same service path as manual ones
|
|
so the permission cache stays correct. The application gains no second
|
|
authorization model.
|
|
6. **No MFA, no password policy engine of our own** (ADR 0019). Both are
|
|
the IdP's.
|
|
|
|
## Decisions taken in #214
|
|
|
|
- **Implementation on `jose` + `fetch`** — the vetted JWT library from
|
|
#188 plus the platform HTTP client. `openid-client` was rejected: no new
|
|
dependency enters the supply chain for a security base function, and the
|
|
code path (discovery, authorize URL, code exchange, JWKS validation) is
|
|
small enough to own.
|
|
- **ID-token algorithms**: explicit `RS256`/`ES256` allowlist; HS* and
|
|
`none` can never verify.
|
|
- **Client authentication**: `client_secret_post` when a secret is
|
|
configured; a public client runs on PKCE alone (PKCE is always sent).
|
|
- **No IdP-initiated single logout**: sessions are short-bounded (#190),
|
|
the leaver case is covered by claim-mapping revocation (#217) and the
|
|
disable flag. Front-channel logout would add an unauthenticated,
|
|
spoofable endpoint for marginal gain.
|
|
- **JIT accounts** arrive ACTIVE and mail-verified, but only when the IdP
|
|
asserts a verified address (`email_verified` must not be false; missing
|
|
e-mail refuses the login). The linking refusal (`oidc_link_required`)
|
|
plus the explicit `GET /auth/oidc/link` flow (audited
|
|
`auth.identity_linked`) is the documented linking rule.
|
|
|
|
## Decisions taken in #215
|
|
|
|
- **Peer check against the TCP peer address only** — a forwarded
|
|
`X-Forwarded-For` is attacker-influenced and never consulted.
|
|
- **Untrusted peer + header ⇒ reject the whole request (403) and audit**
|
|
(`auth.proxy_rejected`), even when a valid session cookie rides along:
|
|
a poisoned request is rejected, not partially trusted.
|
|
- **Trusted peer + header ⇒ the header is the identity**; a session
|
|
cookie never escalates beyond it. No just-in-time creation — the header
|
|
carries no verified e-mail, so accounts come from OIDC or an admin.
|
|
- **mTLS is proxy-terminated**: the application never touches TLS; the
|
|
terminator forwards the certificate subject DN and the configured
|
|
attribute (default CN) is the identity, under the same peer rules.
|
|
|
|
## Decisions taken in #216
|
|
|
|
- **Deploy-level, not runtime**: the switch is the environment variable
|
|
`AUTH_LOCAL_ENABLED` (default true). A compromised Site Admin cannot
|
|
reopen the local path — the runtime-flip residual risk from the
|
|
consequences below therefore does NOT materialize (R-02 closed).
|
|
- **404 semantics** on every marked flow (login, signup, verification,
|
|
resend, password forgot/reset/change), enforced centrally in the auth
|
|
guard via the `@LocalCredentialFlow()` marker; an enumeration fence
|
|
fails when an auth route is neither marked nor on the reviewed
|
|
allowlist, so a new credential flow cannot ship unswitched.
|
|
- **Bootstrap**: complete the first-run setup (or the `SETUP_ADMIN_*`
|
|
pre-seed, which does not run through HTTP routes) BEFORE flipping to
|
|
false — the wizard needs no permanent exemption. The api warns at boot
|
|
when local auth is off and neither OIDC nor proxy auth is configured.
|
|
- **PAT and feed-token issuance stay available** to (IdP-)authenticated
|
|
sessions: they authorize API access under their own switches
|
|
(`api.enabled`, `feeds.enabled`), they are not interactive sign-in.
|
|
|
|
## Consequences
|
|
|
|
- Bootstrapping needs a documented answer: the first-run wizard creates a
|
|
local admin, so either it stays exempt with a stated compensating
|
|
control, or setup itself runs against the IdP. The choice is recorded in
|
|
#216.
|
|
- Whether the switch is deploy-level or runtime matters: a runtime setting
|
|
can be flipped back by a compromised Site-Admin. If it stays runtime,
|
|
that residual risk goes into #231.
|
|
- Existing password hashes remain in the database after the switch. Their
|
|
deletion is out of scope and, being Argon2id, they are not a
|
|
confidentiality problem — but the fact is documented.
|
|
- Session handling is unchanged: OIDC produces a session through the same
|
|
service, so there is exactly one session mechanism (see #190 for its
|
|
bounds).
|
|
- SAML and LDAP stay out. OIDC plus proxy/mTLS covers the environments we
|
|
target; adding SAML would be a new decision.
|
|
|
|
## Implementing issues
|
|
|
|
#214 (OIDC + PKCE), #215 (proxy header / mTLS), #216
|
|
(`auth.local.enabled`), #217 (claim mapping). Depends on #188 for the
|
|
vetted JWT implementation.
|