ADR proposal · BFF OIDC validation + downstream boundaries #63

New Issue

not · 2026-07-01T08:50:58Z

not commented

2026-07-01 08:50:58 +00:00

Context

S-07 (#8) adds the BFF — the single backend the portals talk to (CLAUDE.md §8.3). It exposes POST /self-service/registrations and GET /openbaar/register?q=... for the walking skeleton, validates Keycloak-issued tokens, and fans out to the Domain Service (#6) and projection-api (#7). This is ADR-worthy (§14): a new dependency (JWT bearer auth), and new service boundaries (BFF→domain, BFF→projection).

Decisions to record

Auth model. POST /self-service/registrations requires a valid Keycloak digid-realm JWT; the BFF extracts the bsn claim and forwards it to the domain. Missing/invalid/expired token → 401. GET /openbaar/register is anonymous (the openbaar register is a public lookup, S-09).
The BFF is the portals' only backend (§8.3). Portals never call the domain, ACL, projection, or OpenZaak directly. The BFF orchestrates via typed HTTP clients (base URLs from config); downstream calls are unauthenticated on the internal network for the walking skeleton (a service-to-service auth story is a later slice).
Token validation is Microsoft.AspNetCore.Authentication.JwtBearer against the Keycloak digid realm authority. Unit/BDD tests override the bearer options with a test signing key so valid/invalid/expired tokens can be minted without a live Keycloak; real Keycloak validation is a live-stack verify-bff check.
OpenAPI is generated and committed (services/bff/openapi.json) via .NET's built-in OpenAPI, so S-08's Angular client is generated from it (never hand-written, §10).

Known wrinkle

Keycloak issues tokens whose iss is its browser-facing URL, which differs from the BFF's in-container authority — the classic container OIDC issuer mismatch. Unit tests sidestep it (test key); verify-bff handles it explicitly (issuer/authority alignment). Recorded so it isn't rediscovered.

ADR file docs/architecture/adr-0010-bff-oidc.md lands in the PR that implements #8.

## Context S-07 (#8) adds the **BFF** — the single backend the portals talk to (CLAUDE.md §8.3). It exposes `POST /self-service/registrations` and `GET /openbaar/register?q=...` for the walking skeleton, validates Keycloak-issued tokens, and fans out to the Domain Service (#6) and projection-api (#7). This is ADR-worthy (§14): a new dependency (JWT bearer auth), and new service boundaries (BFF→domain, BFF→projection). ## Decisions to record 1. **Auth model.** `POST /self-service/registrations` requires a valid Keycloak `digid`-realm JWT; the BFF extracts the `bsn` claim and forwards it to the domain. Missing/invalid/expired token → 401. `GET /openbaar/register` is **anonymous** (the openbaar register is a public lookup, S-09). 2. **The BFF is the portals' only backend (§8.3).** Portals never call the domain, ACL, projection, or OpenZaak directly. The BFF orchestrates via typed HTTP clients (base URLs from config); downstream calls are unauthenticated on the internal network for the walking skeleton (a service-to-service auth story is a later slice). 3. **Token validation is `Microsoft.AspNetCore.Authentication.JwtBearer` against the Keycloak `digid` realm authority.** Unit/BDD tests override the bearer options with a test signing key so valid/invalid/expired tokens can be minted without a live Keycloak; real Keycloak validation is a live-stack `verify-bff` check. 4. **OpenAPI is generated and committed** (`services/bff/openapi.json`) via .NET's built-in OpenAPI, so S-08's Angular client is generated from it (never hand-written, §10). ## Known wrinkle Keycloak issues tokens whose `iss` is its browser-facing URL, which differs from the BFF's in-container authority — the classic container OIDC issuer mismatch. Unit tests sidestep it (test key); `verify-bff` handles it explicitly (issuer/authority alignment). Recorded so it isn't rediscovered. ADR file `docs/architecture/adr-0010-bff-oidc.md` lands in the PR that implements #8.

not added the type:adr-proposal area:bff labels 2026-07-01 08:50:59 +00:00

not referenced this issue from a commit

2026-07-01 09:16:53 +00:00

arch(bff): ADR-0010 BFF OIDC validation + downstream boundaries (refs #8, #63)

not referenced a pull request that will close this issue

2026-07-01 09:17:15 +00:00

feat(bff): BFF with one endpoint per portal + OIDC validation (closes #8) #64

not closed this issue

2026-07-01 09:32:45 +00:00

Sign in to join this conversation.