register-referentie/docs/architecture/adr-0013-behandel-portal-wiring.md

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.