[VS-NfD] Implement OIDC Authorization Code with PKCE, Keycloak as reference IdP #214

New Issue

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

fable-5 commented

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

Plan reference: 20-massnahmenplan.md -> P1-1
ADR: ADR 0021
Effort: L (5–6 AT)
Depends on: #188

Context

Authentication is a security base function §52 VSA assigns to the
platform. Delegating it to the operator's IdP is the single most important
step in keeping Dorfteich out of the certification obligation under §51
VSA.

Current state

The data model has the slot: model UserIdentity
(apps/api/prisma/schema.prisma:562–577) — "provider is 'password'
today and 'oidc:' later", @@unique([provider, subject]),
credential holds the Argon2id hash for password identities.
No OIDC implementation exists: a search for oidc across
apps/api/src and packages/shared/src returns nothing outside that
comment. ADR 0007 declares the readiness, not the feature.

Acceptance criteria

Authorization Code flow with PKCE, state and nonce validation,
discovery-based configuration, and JWKS-based token validation using
the vetted library from #188 — no hand-rolled JWT verification.
Identity linking follows the existing model: provider = "oidc:<issuer>", subject from the token; an existing local user is
linked by a documented, deliberate rule (not silently by e-mail).
Login, logout (including IdP-initiated single logout or a documented
decision against it) and session creation reuse the existing session
service — no parallel session mechanism.
Verified against a Keycloak instance; the setup used is documented so
the test is repeatable.
Tests: successful login creates/links the identity; invalid state,
nonce, signature, issuer and audience each rejected; expired token
rejected.
docs/architecture/security.md and #227 document configuration;
ADR 0021 records the decisions.

Out of scope

SAML and LDAP, claim-to-role mapping (#217), and disabling local
authentication (#216).

**Plan reference:** `20-massnahmenplan.md` -> P1-1 **ADR:** ADR 0021 **Effort:** L (5–6 AT) **Depends on:** #188 ## Context Authentication is a security base function §52 VSA assigns to the platform. Delegating it to the operator's IdP is the single most important step in keeping Dorfteich out of the certification obligation under §51 VSA. ## Current state - The data model has the slot: `model UserIdentity` (`apps/api/prisma/schema.prisma:562–577`) — "`provider` is 'password' today and 'oidc:<issuer>' later", `@@unique([provider, subject])`, `credential` holds the Argon2id hash for password identities. - **No OIDC implementation exists**: a search for `oidc` across `apps/api/src` and `packages/shared/src` returns nothing outside that comment. ADR 0007 declares the readiness, not the feature. ## Acceptance criteria - [ ] Authorization Code flow with PKCE, state and nonce validation, discovery-based configuration, and JWKS-based token validation using the vetted library from #188 — no hand-rolled JWT verification. - [ ] Identity linking follows the existing model: `provider = "oidc:<issuer>"`, `subject` from the token; an existing local user is linked by a documented, deliberate rule (not silently by e-mail). - [ ] Login, logout (including IdP-initiated single logout or a documented decision against it) and session creation reuse the existing session service — no parallel session mechanism. - [ ] Verified against a Keycloak instance; the setup used is documented so the test is repeatable. - [ ] Tests: successful login creates/links the identity; invalid state, nonce, signature, issuer and audience each rejected; expired token rejected. - [ ] `docs/architecture/security.md` and #227 document configuration; ADR 0021 records the decisions. ## Out of scope SAML and LDAP, claim-to-role mapping (#217), and disabling local authentication (#216).

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

fable-5 added the

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

fable-5 referenced this issue

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

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

fable-5 referenced this issue

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

[VS-NfD] Add a hard `auth.local.enabled = false` switch covering every local credential flow #216

fable-5 referenced this issue

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

[VS-NfD] Map IdP groups and roles onto the permission model #217

fable-5 referenced this issue

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

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

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 from a commit

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

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

fable-5 commented

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

Implemented in PR #282 (commit 5796b7a); merged via the fast-forward chain PRs #283-#285 (runs 602-604 green over the cumulative diffs; #282 own run 601 failed only on the known action-cache runner signature). CD 609 green, readyz test+int ok; GET /auth/methods live answers {local:true, oidc:null} (OIDC deploy-level unconfigured on the stages, as intended). OIDC Authorization Code + PKCE on jose+fetch (no new dependency), discovery + JWKS validation (RS256/ES256 allowlist, issuer/audience/expiry/nonce), signed state cookie with a dedicated HKDF purpose, JIT accounts (verified-mail required), NO silent adoption by e-mail (oidc_link_required + explicit link flow, audited, catalogue v1.3). 5 e2e tests against a protocol-faithful fake IdP; verified end-to-end against real Keycloak 26.0 via curl (repeatable procedure in security.md, section External authentication).

Implemented in PR #282 (commit 5796b7a); merged via the fast-forward chain PRs #283-#285 (runs 602-604 green over the cumulative diffs; #282 own run 601 failed only on the known action-cache runner signature). CD 609 green, readyz test+int ok; GET /auth/methods live answers {local:true, oidc:null} (OIDC deploy-level unconfigured on the stages, as intended). OIDC Authorization Code + PKCE on jose+fetch (no new dependency), discovery + JWKS validation (RS256/ES256 allowlist, issuer/audience/expiry/nonce), signed state cookie with a dedicated HKDF purpose, JIT accounts (verified-mail required), NO silent adoption by e-mail (oidc_link_required + explicit link flow, audited, catalogue v1.3). 5 e2e tests against a protocol-faithful fake IdP; verified end-to-end against real Keycloak 26.0 via curl (repeatable procedure in security.md, section External authentication).

fable-5 closed this issue

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

Sign in to join this conversation.