diff --git a/docs/architecture/adr-0013-behandel-portal-wiring.md b/docs/architecture/adr-0013-behandel-portal-wiring.md new file mode 100644 index 0000000..2c04a83 --- /dev/null +++ b/docs/architecture/adr-0013-behandel-portal-wiring.md @@ -0,0 +1,76 @@ +# ADR-0013: Behandel-portal wiring — multi-realm BFF auth, werkbak from Flowable tasks, decision completes the task + +- **Status:** Accepted +- **Date:** 2026-07-15 +- **Deciders:** Respellion engineering +- **Relates to:** #84 (adr-proposal), S-12 (#13); builds on ADR-0010 (BFF OIDC), ADR-0011 (approval status flow), ADR-0009 (external-task worker), ADR-0008 (read projection) + +## Context + +S-12 adds the behandel-portal: a behandelaar logs in, sees a **werkbak** of registrations awaiting +beoordeling, and decides each (goedkeuren/afwijzen). Three questions had no obvious answer and shape +the whole slice. + +1. **Which realm authenticates behandelaars, and how does the BFF accept it?** Citizens use the + `digid` realm (ADR-0010); staff use a separate `medewerker` realm with roles (`behandelaar`, + `teamlead`). Keycloak realms are distinct issuers with distinct signing keys, so the BFF's single + `digid`-realm JWT validation rejects a medewerker token outright. +2. **Where does the werkbak get its data?** The registrations awaiting beoordeling could come from + the read projection (status-filtered rows) or from the Flowable `Beoordelen` user tasks (S-12b). +3. **How does a decision correlate to the workflow?** The process parks at the `Beoordelen` user + task; the decision must advance it, and also apply the domain transition (ADR-0011). + +## Decision + +**The BFF validates a second realm for behandel endpoints; the werkbak is the set of open Flowable +`Beoordelen` tasks (read through the domain); and a decision both applies the domain transition and +completes the Flowable task.** + +- **Multi-realm BFF auth.** The BFF registers a second JWT bearer scheme (`medewerker`, authority = + the medewerker realm) alongside the default `digid` scheme. `/behandel/*` endpoints require an + authorization policy bound to the `medewerker` scheme **and** the `behandelaar` role. Keycloak puts + realm roles in the nested `realm_access.roles` claim, which ASP.NET does not map automatically, so + the scheme's `OnTokenValidated` lifts those roles onto the principal as role claims. Self-service + keeps the `digid` scheme. Audience validation stays off (ADR-0010's deferred hardening). +- **Werkbak = Flowable user tasks (via the domain).** The domain's `Werkbak` query reads the open + `Beoordelen` tasks from the Workflow Client (§8.2, `IUserTaskClient`) and enriches each with its + aggregate's bsn + status; `GET /behandel/werkbak` exposes it and the BFF proxies it behind the + behandelaar policy. The list **is** the authoritative set of claimable/decidable work items, so a + decision acts on a real task with no separate correlation store. The read projection stays the + anonymous openbaar model — we do **not** project `IN_BEHANDELING` or populate staff-only personal + data (both deferred in ADR-0008) just to render a staff view. +- **Decision completes the task (S-12c-2).** A behandelaar decision applies the domain transition + (aggregate + ACL for approval, per ADR-0011) **and** completes the Flowable `Beoordelen` task + (looked up by registrationId), so the process advances. Implemented in the next sub-slice; recorded + here so the boundary is decided up front. + +Delivery is split: **S-12c-1** (this PR) = multi-realm auth + werkbak read; **S-12c-2** = the decide +endpoint + task completion. + +## Consequences + +**Positive** + +- Staff and citizens are cleanly separated by realm; the `behandelaar` role gates the behandel API. +- The werkbak reflects exactly what a behandelaar can act on; claim/decide need no extra correlation. +- No premature projection changes — the openbaar read model stays focused and personal-data-free. +- Only the ACL/Workflow Client talk to their peers; the BFF still fans out only to domain/projection + (§8.3). + +**Negative / costs** + +- The BFF now depends on two Keycloak realms being reachable (`Keycloak:MedewerkerAuthority`). +- Rendering the werkbak fans out to Flowable (one task query) plus a store read per task — acceptable + for the caseload sizes here; a denormalized staff read model is an additive follow-up if needed. +- Realm separation (distinct issuers/keys) is validated live, not in the BFF unit tests, where issuer + validation is off and one test key signs both realms; the tests exercise the role-based authorization. + +## Alternatives considered + +- **Werkbak from the read projection** — rejected for now: needs new plumbing to project + `IN_BEHANDELING` and to populate staff-only bsn/naam (deferred, ADR-0008), plus a separate way to + find the Flowable task at decide-time. Revisit if a high-volume denormalized staff view is needed. +- **One JWT scheme accepting both realms (issuer validation off)** — rejected: trusting multiple + issuers without validation is a security regression; two schemes keep each realm's issuer/key checked. +- **A dedicated behandel BFF/service** — rejected as premature; one BFF with per-endpoint policies is + enough at this size and keeps §8.3 simple.