#215: trusted reverse-proxy header / mTLS client-certificate path #283

fable-5 · 2026-07-31T13:09:53+02:00

fable-5 commented

2026-07-31 13:09:53 +02:00

Off unless AUTH_PROXY_HEADER and AUTH_PROXY_TRUSTED_PEERS are both set. Peer check against the TCP peer only; header from any other peer = reject + audit (auth.proxy_rejected, catalogue v1.4) even alongside a valid session; from a trusted peer the header IS the identity and a cookie never escalates past it; feature off = header inert. Explicit mapping (username/e-mail), no JIT; mtls-dn maps the configured DN attribute from the terminator-forwarded subject. Trust boundary stated in security.md, VS-NfD security documentation and the hardening guide. Stacked on #214. Refs #215

fable-5 added 2 commits 2026-07-31 13:09:53 +02:00

#214 : OIDC Authorization Code with PKCE, Keycloak as reference IdP

CI / Lint, typecheck, test (pull_request) Failing after 14s

Details

CI / Import/export fidelity gate (pull_request) Has been skipped

Details

CI / Build container images (pull_request) Has been skipped

Details

CI / Auth e2e pack (pull_request) Has been skipped

Details

5796b7a5dd

External authentication (ADR 0021) built on jose (#188's vetted library)
plus fetch — no new dependency enters the supply chain for a security
base function. Discovery-configured; ID tokens validate against the
IdP's JWKS under an explicit RS256/ES256 allowlist with issuer,
audience, expiry and nonce binding. State, nonce and the PKCE verifier
travel in a signed HttpOnly Lax cookie keyed by a dedicated HKDF
purpose (oidc-state, ADR 0020).

Deploy-level configuration (OIDC_ISSUER/CLIENT_ID/CLIENT_SECRET/SCOPES/
PROVIDER_LABEL): who authenticates users is a platform decision. The
login page discovers the provider via GET /auth/methods and renders the
SSO button (i18n de+en).

Identities use the existing slot (provider oidc:<issuer>, subject from
the token). First login creates the account just-in-time — ACTIVE and
mail-verified only when the IdP asserts a verified address. An existing
local account is NEVER adopted silently by e-mail (account-takeover
path): login refuses with oidc_link_required and the owner links
explicitly via GET /auth/oidc/link (audited auth.identity_linked,
catalogue v1.3). Sessions come from the one existing session service.

Tests run the full flow against a protocol-faithful fake IdP: PKCE
verifier at the token endpoint, JIT creation incl. personal pond,
invalid state/nonce/signature/issuer/audience/expiry each rejected, the
linking refusal and the explicit link flow. Verified end-to-end against
a real Keycloak 26.0 (repeatable procedure documented in security.md
§External authentication).

Refs #214.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

#215 : trusted reverse-proxy header / mTLS client-certificate path

CI / Lint, typecheck, test (pull_request) Successful in 6m44s

Details

CI / Build container images (pull_request) Successful in 4m42s

Details

CI / Auth e2e pack (pull_request) Successful in 9m15s

Details

CI / Import/export fidelity gate (pull_request) Successful in 59s

Details

CD / Deploy to Test (push) Blocked by required conditions

Details

CD / Smoke tests against Test (push) Blocked by required conditions

Details

CD / Promote to Int (push) Blocked by required conditions

Details

CI / Auth e2e pack (push) Blocked by required conditions

Details

CI / Import/export fidelity gate (push) Blocked by required conditions

Details

CI / Build container images (push) Blocked by required conditions

Details

CD / Build and push images (push) Has been cancelled

Details

CI / Lint, typecheck, test (push) Has been cancelled

Details

4c7f001cab

For perimeters that authenticate before the application (ADR 0021 §4).
Off unless BOTH AUTH_PROXY_HEADER and AUTH_PROXY_TRUSTED_PEERS are set —
nothing about the header is guessed. The peer check runs against the TCP
peer address only (a forwarded header is attacker-influenced): a request
carrying the header from any other peer is rejected outright and audited
as auth.proxy_rejected (catalogue v1.4) — that is a spoof attempt, not a
misconfiguration — even when a valid session cookie rides along. From a
trusted peer the header IS the identity; a session cookie never
escalates beyond it; with the feature off the header is inert.

Mapping is explicit (AUTH_PROXY_MAP: username or e-mail); deliberately
no just-in-time creation — the header carries no verified address. The
mTLS variant (AUTH_PROXY_MODE=mtls-dn) maps the configured attribute
(default CN) out of the certificate subject DN the TLS terminator
forwards, under the same peer rules. Session-less proxy requests key the
read trail per user (user:<id>).

The trust boundary is stated in security.md (the section an assessor
reads closest), the VS-NfD security documentation and the hardening
guide's deploy table. Tests cover all four decisions: off = inert,
trusted peer authenticates (username and DN mapping), untrusted peer
rejected + audited, no escalation past a session cookie.

Refs #215.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

fable-5 merged commit 4c7f001cab into main

2026-07-31 13:35:49 +02:00

fable-5 referenced this pull request

2026-07-31 13:47:15 +02:00

[VS-NfD] Support a trusted reverse-proxy header or mTLS client certificate as an alternative path #215

Sign in to join this conversation.

No reviewers