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

New Issue

fable-5 · 2026-07-30T01:43:47+02:00

fable-5 commented

2026-07-30 01:43:47 +02:00

Plan reference: 20-massnahmenplan.md -> P1-1
ADR: ADR 0021
Effort: M (2 AT)
Depends on: #214

Context

Some authority environments terminate authentication at the perimeter and
expect the application to trust it. Supporting that avoids forcing an IdP
into an architecture that already solved authentication — but a trusted
header is a loaded gun if it is trusted unconditionally.

Current state

Authentication is cookie/session based
(apps/api/src/auth/auth.guard.ts, sessions.service.ts) plus PATs; no
header- or certificate-based identity path exists.

Acceptance criteria

Header-based identity is off by default and requires both an
explicit switch and an allowlist of trusted peer addresses; a request
arriving from an untrusted peer with the header is rejected and
audited.
The configured header name and the identity mapping are explicit
configuration, never guessed.
mTLS variant: the certificate subject/attribute used as identity is
configurable, with the same trust-boundary rules.
Tests: header from untrusted peer ignored and audited; header from
trusted peer authenticates; header ignored entirely while the switch
is off; spoofed header alongside a session cookie does not escalate.
docs/architecture/security.md documents the trust boundary
unambiguously — this is the section an assessor will read closest.

Out of scope

Terminating TLS in the application, and certificate lifecycle management.

**Plan reference:** `20-massnahmenplan.md` -> P1-1 **ADR:** ADR 0021 **Effort:** M (2 AT) **Depends on:** #214 ## Context Some authority environments terminate authentication at the perimeter and expect the application to trust it. Supporting that avoids forcing an IdP into an architecture that already solved authentication — but a trusted header is a loaded gun if it is trusted unconditionally. ## Current state - Authentication is cookie/session based (`apps/api/src/auth/auth.guard.ts`, `sessions.service.ts`) plus PATs; no header- or certificate-based identity path exists. ## Acceptance criteria - [ ] Header-based identity is **off by default** and requires both an explicit switch and an allowlist of trusted peer addresses; a request arriving from an untrusted peer with the header is rejected and audited. - [ ] The configured header name and the identity mapping are explicit configuration, never guessed. - [ ] mTLS variant: the certificate subject/attribute used as identity is configurable, with the same trust-boundary rules. - [ ] Tests: header from untrusted peer ignored and audited; header from trusted peer authenticates; header ignored entirely while the switch is off; spoofed header alongside a session cookie does not escalate. - [ ] `docs/architecture/security.md` documents the trust boundary unambiguously — this is the section an assessor will read closest. ## Out of scope Terminating TLS in the application, and certificate lifecycle management.

fable-5 added this to the M27 — VS-NfD: external authentication milestone 2026-07-30 01:43:47 +02:00

fable-5 added the

effort:M

area:auth

vs-nfd

labels 2026-07-30 01:43:47 +02:00

fable-5 referenced this issue

2026-07-30 01:43:56 +02:00

[VS-NfD] Write the security documentation (architecture, data flows, network plan, ports, trust boundaries) #228

fable-5 referenced this issue

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

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

fable-5 referenced this issue

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

#216: hard AUTH_LOCAL_ENABLED switch over every local credential flow #284

fable-5 referenced this issue from a commit

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

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

fable-5 commented

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

Implemented in PR #283 (commit 4c7f001), merged fast-forward (run 602 green); CD 609 green. Trusted-proxy/mTLS path off unless AUTH_PROXY_HEADER and AUTH_PROXY_TRUSTED_PEERS are both set; peer check against the TCP peer only; header from an untrusted peer rejects the request and is audited (auth.proxy_rejected, catalogue v1.4) even alongside a valid session; a cookie never escalates past the header identity; 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 documented in security.md, the VS-NfD security documentation (section 4) and the hardening guide deploy table. 4 e2e tests cover all four decisions.

Implemented in PR #283 (commit 4c7f001), merged fast-forward (run 602 green); CD 609 green. Trusted-proxy/mTLS path off unless AUTH_PROXY_HEADER and AUTH_PROXY_TRUSTED_PEERS are both set; peer check against the TCP peer only; header from an untrusted peer rejects the request and is audited (auth.proxy_rejected, catalogue v1.4) even alongside a valid session; a cookie never escalates past the header identity; 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 documented in security.md, the VS-NfD security documentation (section 4) and the hardening guide deploy table. 4 e2e tests cover all four decisions.

fable-5 closed this issue

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

Sign in to join this conversation.