# 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.