Niek Otten
9c3da48d8e
All checks were successful
## What & why First half of **S-12c** (behandel-portal backend), per **ADR-0013** (decisions recorded in #84): - **BFF multi-realm auth.** A second JWT bearer scheme (`medewerker`) alongside the default `digid` scheme. On validation it lifts Keycloak's `realm_access.roles` onto the principal, and a `behandelaar` policy (medewerker scheme + `behandelaar` role) gates `/behandel/*`. Self-service keeps the digid scheme. - **Werkbak = Flowable tasks.** The domain `Werkbak` query reads the open `Beoordelen` tasks (§8.2, S-12b's `IUserTaskClient`) and enriches each with its aggregate's bsn + status; `GET /behandel/werkbak` (domain) is proxied by the BFF `GET /behandel/werkbak` behind the behandelaar policy. The read projection stays the anonymous openbaar model (no premature `IN_BEHANDELING`/personal-data plumbing — deferred in ADR-0008). Behavior: `/behandel/werkbak` is **401** without a token, **403** for a medewerker lacking the role, **200 + werkbak** for a behandelaar. **S-12c-2** (next): `POST /behandel/registrations/{id}/decide` → domain decision + complete the Flowable task. ## Definition of Done - [x] Linked issue: #13 (umbrella, `refs`); closes the adr-proposal #84 - [x] Tests first; red → green per layer - [x] Unit + acceptance green (`make unit`): domain 78, bff 23, acceptance 9 (+ acl/event-subscriber unaffected) - [x] api-client `test` green; openapi.json regenerated (drift guard passes) - [x] Mutation ≥ break(90): **domain 100%, bff 100%** - [x] ADR-0013 added; `Keycloak__MedewerkerAuthority` wired into compose - [ ] CI green (pending) Part of #13. closes #84 Reviewed-on: #85
77 lines
4.9 KiB
Markdown
77 lines
4.9 KiB
Markdown
# 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.
|