diff --git a/docs/architecture/adr-0031-mfa-on-the-medewerker-realm.md b/docs/architecture/adr-0031-mfa-on-the-medewerker-realm.md new file mode 100644 index 0000000..0f8c8b7 --- /dev/null +++ b/docs/architecture/adr-0031-mfa-on-the-medewerker-realm.md @@ -0,0 +1,49 @@ +# ADR-0031 — MFA on the medewerker realm, with a fixture TOTP secret + +- **Status:** Accepted +- **Date:** 2026-09-03 +- **Slice:** S-15c (Gitea #132) + +## Context + +Staff (behandelaar, teamlead, beheerder) act on citizens' registrations and on the ACL's +default-fill: the highest-privilege logins in the platform. The medewerker realm protected +them with a password alone, while the citizen realms (digid, eherkenning, eidas) mock +brokers that carry their own assurance levels. A reference application that demonstrates a +government architecture should show MFA on the staff realm. + +Two things had to be decided: **how** to enforce OTP in a realm export, and **how the +automated checks and a human demo obtain a code** — the e2e drives a real browser login and +`make keycloak-smoke` drives a real password grant, so neither can scan a QR. + +## Decision + +**Enforce OTP by giving every seeded medewerker a TOTP credential**, rather than replacing +Keycloak's browser flow with a copy whose OTP execution is `REQUIRED`. + +Keycloak's stock `browser` and `direct grant` flows both contain a *conditional OTP* +subflow that fires when the user has an OTP credential. Seeding the credential therefore +turns the challenge on for every seeded user, in both flows, without duplicating ~40 lines +of flow JSON into the export. `CONFIGURE_TOTP` is additionally set as a **default required +action**, so a medewerker created later must enrol before their first login. + +**The seeded secret is a fixed, committed fixture** (`BIGMEDEWERKEROTPSEED`) shared by all +medewerkers. Codes are then computable: `infra/keycloak/check_realms.py` (Python, stdlib +`hmac`) and `tests/e2e/medewerker-login.ts` (Node `crypto`) each implement RFC 6238 in +about six lines — no OTP dependency on either side, and no enrolment step in the tests. + +## Consequences + +- A password alone no longer yields a token on the medewerker realm; `check_realms.py` + asserts that refusal, so the enforcement cannot silently regress. +- Every medewerker login in the e2e goes through `loginMedewerker()`, which submits the OTP + form. New staff specs must use it. +- **The secret is public.** It is a demo fixture and worthless outside this synthetic + stack, in the same class as the committed `test123` passwords and the mock DigiD broker. + A real deployment enrols per-user authenticators (or federates to DigiD Machtigen / + eHerkenning at the required assurance level) and seeds no credentials at all. +- Enforcement is *effectively* realm-wide but *technically* per-user: the conditional + subflow is what fires. A medewerker whose OTP credential were removed would fall back to + the required action at next login (enrol, then challenge) rather than skipping MFA — an + acceptable equivalence for this purpose, and the reason the required action is set. +- Reversal is a one-file edit: drop the `otp` credentials and the `requiredActions` block. diff --git a/docs/demo-script.md b/docs/demo-script.md index 25423aa..5172b33 100644 --- a/docs/demo-script.md +++ b/docs/demo-script.md @@ -140,7 +140,8 @@ zaaktype cache). Store is in-memory: an edit reverts to the configured env on re ```bash make up -# 1. Log in as bram-beheerder / test123 → "Default-fill" tab → change a value → Opslaan. +# 1. Log in as bram-beheerder / test123 + OTP (`python3 infra/keycloak/check_realms.py otp`) +# → "Default-fill" tab → change a value → Opslaan. open http://localhost:8143/default-fill # # 2. Automated: the ACL uses the current default-fill per zaak (unit) and the endpoints are behind the @@ -161,7 +162,8 @@ directly (ADR-0025); managing the default-fill config (S-15b) and MFA (S-15c) co ```bash make up -# 1. Log in as bram-beheerder / test123 → the catalogus lists the published zaaktypen. +# 1. Log in as bram-beheerder / test123 + OTP (`python3 infra/keycloak/check_realms.py otp`) +# → the catalogus lists the published zaaktypen. open http://localhost:8143 # # 2. Automated (a CI verify-stack e2e): a beheerder logs in and sees BIG-REGISTRATIE. @@ -304,7 +306,8 @@ make verify-local # → "OK — a fresh local stack completed the flow with # 3. Or by hand in the browser: log in at http://localhost:8140 (jan-burger / test123), submit + # upload a PDF, then approve it in the werkbak at http://localhost:8142 (merel-behandelaar / -# test123); it shows as INGESCHREVEN in the openbaar register at http://localhost:8141. +# test123 + OTP, see S-15c); it shows as INGESCHREVEN in the openbaar register at +# http://localhost:8141. ``` > The zaaktype is discovered by the ACL itself since S-27 (below); `local-seed`'s `acl.env` now @@ -589,7 +592,7 @@ or **afwijzen** — which also completes the Beoordelen task so the process adva ```text # 1. Open the behandel portal and log in as a behandelaar (medewerker realm): -# http://localhost:8142/ → merel-behandelaar / test123 +# http://localhost:8142/ → merel-behandelaar / test123 + OTP # # 2. The werkbak lists the registrations awaiting beoordeling (referentie / bsn / status). # Find the reference from the submit confirmation and click "Goedkeuren" on that row. @@ -812,3 +815,32 @@ make verify-domain # → "the timed-out registration's zaak was cancelled to `POST /annuleringen` → ZGW `resultaten` + `statussen` (Geannuleerd); the aggregate then moves to `Verlopen`. The ACL cancels the zaak **before** the aggregate is expired, so a failed ZGW call leaves the job for redelivery rather than diverging the two (ADR-0019). + +--- + +## S-15c — MFA on the medewerker realm (#132, ADR-0031) + +**Outcome:** staff logins (behandel + beheer portals) need a **second factor**. The medewerker realm +seeds every medewerker with a TOTP credential, so Keycloak's conditional-OTP step challenges them in +both the browser flow and the direct grant; a password alone no longer yields a token. `CONFIGURE_TOTP` +is a default required action, so a medewerker added later must enrol first. Citizen realms (digid, +eherkenning, eidas) are unchanged — they mock brokers that carry their own assurance. + +```bash +# 1. Manual: log in to the behandel portal. After username + password Keycloak asks for a code. +python3 infra/keycloak/check_realms.py otp # a valid code, right now +open http://localhost:8142 # merel-behandelaar / test123 + that code +# +# 2. Automated: the realm smoke check asserts the password alone is REFUSED, then that +# password + TOTP succeeds and still carries the behandelaar role: +make keycloak-smoke # → "medewerker merel-behandelaar password-only login refused [OK]" +# +# 3. End-to-end: every staff login in the e2e goes through the OTP prompt (loginMedewerker): +make verify-e2e # → registration.spec (behandelaar approves), catalogus.spec, default-fill.spec +``` + +**The path:** the seeded `otp` credential in `infra/keycloak/realms/medewerker-realm.json` activates +Keycloak's stock conditional-OTP subflow — no custom browser flow. The fixture secret is shared and +committed on purpose so the checks can compute codes; a real deployment enrols per-user authenticators +(ADR-0031). + diff --git a/docs/runbooks/keycloak.md b/docs/runbooks/keycloak.md index df43d93..976f95a 100644 --- a/docs/runbooks/keycloak.md +++ b/docs/runbooks/keycloak.md @@ -23,6 +23,9 @@ login per realm and asserts the identifying claim: | eidas | pierre-dupont | `eidas_id` | | medewerker | merel-behandelaar | role `behandelaar` | +The medewerker row also asserts that the password **alone** is refused — that realm +enforces MFA (below). + All test users / credentials are in [../synthetic-data.md](../synthetic-data.md). ## Notes @@ -35,3 +38,30 @@ All test users / credentials are in [../synthetic-data.md](../synthetic-data.md) - **Image** pinned to `quay.io/keycloak/keycloak:26.1`. - Claims are injected by OIDC protocol mappers on `big-portal` (user attribute → token claim); `medewerker` roles come through `realm_access.roles`. + +## MFA on the medewerker realm (S-15c) + +Staff logins (behandel + beheer portals) need a second factor; citizen/company realms +(digid, eherkenning, eidas) do not. Two halves in `medewerker-realm.json`: + +- Every seeded medewerker carries a **TOTP credential** with the fixture secret + `BIGMEDEWERKEROTPSEED`, so Keycloak's built-in *conditional OTP* step fires on every + login — browser flow (an `#otp` prompt after the password) and direct grant (a `totp` + form field) alike. +- `CONFIGURE_TOTP` is a **default required action**, so any medewerker added later must + enrol an authenticator before the first login. + +See [../architecture/adr-0031-mfa-on-the-medewerker-realm.md](../architecture/adr-0031-mfa-on-the-medewerker-realm.md). + +### Getting a code + +```bash +python3 infra/keycloak/check_realms.py otp # prints a valid 6-digit code right now +``` + +Or enrol a phone once: the secret in base32 is `IJEUOTKFIRCVORKSJNCVET2UKBJUKRKE` +(`otpauth://totp/medewerker?secret=IJEUOTKFIRCVORKSJNCVET2UKBJUKRKE`). The e2e computes its +own code in `tests/e2e/medewerker-login.ts`. + +**Fixture only.** A shared, committed secret is a demo convenience, never a production +posture — see the ADR's consequences. diff --git a/docs/synthetic-data.md b/docs/synthetic-data.md index ccdd538..853ba5b 100644 --- a/docs/synthetic-data.md +++ b/docs/synthetic-data.md @@ -19,6 +19,11 @@ All test users share the password **`test123`**. | `eidas` | eIDAS (EU) | `pierre-dupont` | `eidas_id` = `FR/NL/AB-1234-5678` | | `medewerker` | Internal staff | `merel-behandelaar` | role `behandelaar` | | `medewerker` | Internal staff | `tom-teamlead` | roles `behandelaar`, `teamlead` | +| `medewerker` | Internal staff | `bram-beheerder` | role `beheerder` | + +`medewerker` users additionally need a **second factor**: that realm enforces MFA (S-15c, +ADR-0031). All three share the fixture TOTP secret `BIGMEDEWERKEROTPSEED`; print a current +code with `python3 infra/keycloak/check_realms.py otp`. The identifying claims are injected via OIDC protocol mappers on `big-portal` (user-attribute → token claim); `medewerker` roles appear in `realm_access.roles`. @@ -32,5 +37,8 @@ curl -s -X POST \ -d username=jan-burger -d password=test123 -d scope=openid | jq -r .access_token ``` +For a `medewerker` user, add `-d totp=$(python3 infra/keycloak/check_realms.py otp)` — +without it the grant is refused with `invalid_grant`. + Decode the JWT payload to see the `bsn` claim. `make keycloak-smoke` checks every realm automatically. diff --git a/infra/keycloak/check_realms.py b/infra/keycloak/check_realms.py index 4cb0965..240d22d 100644 --- a/infra/keycloak/check_realms.py +++ b/infra/keycloak/check_realms.py @@ -86,4 +86,9 @@ def main(): if __name__ == "__main__": - main() + # `check_realms.py otp` prints a current code for the fixture secret — what a human demoing + # the medewerker portals types at Keycloak's OTP prompt (docs/runbooks/keycloak.md). + if len(sys.argv) > 1 and sys.argv[1] == "otp": + print(totp()) + else: + main()