dorfteich/docs/architecture/adr/0021-external-authentication.md

# ADR 0021: External authentication via OIDC; local passwords optional

- Status: accepted (2026-07-31)
- 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** (realized
   deploy-level as `AUTH_LOCAL_ENABLED`, see #216 below). "In full" means
   every interactive credential flow: password login, self-service
   signup, password reset, verification-as-login. PAT and feed-token
   issuance deliberately stays available to IdP-authenticated sessions —
   they authorize API access under their own switches and are not
   interactive sign-in (#216). 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.

## Decisions taken in #217

- **Reconciliation at login**, not by background sync: fresh claims exist
  only there; between logins the leaver case belongs to the IdP (no new
  login) and the operator's disable flag.
- **Ownership via `role_grants.origin` and `users.is_site_admin_managed`**
  — the mapping creates, updates and revokes only what it owns; manual
  grants and hand-promoted admins always win. A colliding manual grant is
  left in place rather than adopted.
- **Failure containment**: unknown pond slugs and the last-Pond-Admin
  protection log-and-skip — a mapping problem must never lock users out.
- Full semantics: `docs/architecture/permissions.md` §IdP claim mapping.

## 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.