atomic-design-poc/docs/reference/roles-and-access.md

Roles & access (ABAC) — quick reference

A short, practical reference for which roles exist, how to switch between them, and what each unlocks. For the full design and rationale see PRD-0002 — Attribute-Based Access Control.

Login vs. role — they are separate

Login is faked. This POC has one hardcoded, stubbed DigiD user (a 9-digit BSN); there is no real identity provider and you do not pick a role when you log in.

The acting role is a separate, dev-only stand-in for the coarse role a real AD/OIDC identity would carry. It is orthogonal to the login user — you log in as the one faked user, then choose an acting role to exercise the drafter/approver/admin flows.

The three roles

drafter (default) · approver · admin — defined by the Role type in src/app/shared/domain/role.ts.

How to switch role (dev only)

Both are wired only under isDevMode() — they do not exist in a production build.

• Dev switcher (easiest): open the ⚙ state panel (bottom-right in a dev build) and pick a role from the role dropdown. The page reloads with the new role.
• ?role= query param: append ?role=drafter, ?role=approver, or ?role=admin to any URL. The value is sticky for the browser tab (sessionStorage), so it survives navigation that drops the query param. An unknown value falls back to drafter; open a fresh tab or set ?role=drafter to reset.

Mechanism: src/app/shared/infrastructure/role.ts reads the role and the HTTP interceptor stamps it as an X-Role header on role-aware requests; the backend resolves it into a Principal.

Actor kinds (backend, WP-62)

X-Role/Principal above is a coarse role that applies to either of two actor kinds the backend now models (ADR-0002 §3): a zorgverlener (this SSP's citizen — has a BSN) or a medewerker (backoffice employee — no BSN, has Rollen). StubIdentityProvider picks the medewerker kind from a dev header, X-Medewerker (+ X-Rollen), mirroring X-Role/X-Subject above — the SSP's FE never sends either header; they exist only for the backend's own tests and for the behandelportal (WP-64+) to use later. Authz.CanBeoordelen(caller) is the first medewerker capability — a rol-based decision flag (MedewerkerRol.Behandelaar), not a role entry on /me, since /me's RoleCapabilities is keyed on Principal and can't see the actor kind.

What each role unlocks

Capabilities are resolved server-side (backend/src/BigRegister.Api/Domain/Authorization/Authz.cs, RoleCapabilities) and returned by GET /me.

Role	Capabilities (/me)	Reaches
drafter	(none of the admin capabilities)	Composes letters; the only role that may reveal a BSN
approver	brief:approve, brief:reject, brief:send	Reviews/approves letters (four-eyes: approver ≠ drafter)
admin	orgtemplate:edit, stamdata:edit, cases:manage	Huisstijl /brief/huisstijl, Stamdata /beheer/stamdata, Aanvragen /beheer/zaken

The admin pages appear in the header nav and in the dashboard "Beheer" section whenever the matching capability is present — otherwise they are reachable only by URL (and the route guard redirects a user who lacks the capability back to /dashboard).

The one principle

Identity (AD/OIDC, faked here) supplies coarse roles; the app owns a fine-grained capability model on top. The same Authz check both emits a capability (on GET /me, consumed by AccessStore in src/app/shared/application/access.store.ts) and enforces the endpoint — one source of truth, so the two can't drift. The UI only renders decisions; it never derives access from a role. Anything tied to a specific resource's live state (e.g. may-I-edit this letter, reveal this BSN) rides that screen's decision DTO rather than /me.

See also

• PRD-0002 — ABAC — full design.
• backend/src/BigRegister.Api/Domain/Authorization/Authz.cs — role → capability, and the enforce twin.
• src/app/shared/infrastructure/role.ts — the dev ?role= reader + X-Role.
• src/app/shared/application/access.store.ts — how the FE mirrors /me capabilities (deny-by-default).