learning-platform/docs/auth-spec.md

Authentication — Azure (Entra ID) login

Implemented for issue #16. Replaces the previous client-side PIN login. Hardened for issue #18 (migratie-ledger-sync + env-onafhankelijke provider-reconciliatie).

Doel

Elke gebruiker logt in met zijn Respellion Microsoft (Azure Entra ID)-account. Bij de eerste login wordt automatisch een team_members-record aangemaakt. Er is geen PIN, geen handmatige user-aanmaak en geen client-side wachtwoordcontrole meer.

Architectuur in één oogopslag

Browser (SPA)                PocketBase (auth)                 Entra ID
─────────────                ─────────────────                 ────────
"Sign in with Microsoft"
   └─ pb.collection('team_members')
        .authWithOAuth2({provider:'oidc'})
                      ──────────────────►  opens OIDC popup ───► login.microsoftonline.com
                                           token exchange   ◄───  (server-side, client secret)
                      ◄──────────────────  auth record + token
   pb.authStore (token in localStorage)

• PocketBase is de OIDC-client. De token-exchange en het client-secret blijven server-side in PocketBase — er is geen aparte backend en geen client-side key.
• team_members is een PocketBase auth-collection. De record-id blijft de user-identifier die alle voortgangscollecties (test_results, on_demand_attempts, micro_learning_completions, leaderboard, theme_session_completions) als user_id referencen.
• Sessie = pb.authStore (token in localStorage), niet langer een team_members.id in sessionStorage.

Belangrijke beslissingen (ADR)

ADR	Beslissing	Reden
001	OIDC-provider tegen Entra v2-endpoints i.p.v. eigen MSAL-flow of header-trust	Sluit aan op "PocketBase = enige backend"; secret server-side; auto-provisioning gratis; werkt los van de perimeter-implementatie
002	team_members hergebruikt als auth-collection (zelfde naam)	Alle user_id-referenties blijven werken; minimale blast-radius
003	Provisioning + admin-rol via pb_hooks/team_members.pb.js	Rol-logica server-side, niet in de client
004	Admin-rol via e-mail-allowlist (ENTRA_ADMIN_EMAILS), escalate-only bij elke login (aangepast in #27)	Allow-list garandeert admin (promotie werkt bij volgende login) maar demoteert niet meer — anders zou elke TeamManager-promotie bij de volgende login worden teruggedraaid. Demotie via TeamManager; allow-list-leden demoteer je door ze van de lijst te halen
005	API-rules → @request.auth.id != "" op alle app-collecties	Geen anonieme toegang meer; admins/users zijn beide geauthenticeerd
006	Baseline-ledger-sync migratie voor out-of-band geprovisionede DB's	Labs/prod draaide historisch zonder --migrationsDir; replay van de historie crashte PB (issue #18). De vroegst-sorterende migratie markeert de historie als applied wanneer schema bestaat maar de ledger leeg is
007	Migratie = structuur, hook = configuratie	De OIDC-provider wordt bij elke start (en per cron-minuut) gereconcilieerd vanuit ENTRA_* env door pb_hooks/entra_oidc.pb.js; een one-shot migratie die van deploy-time env afhangt kan OAuth2 anders permanent uitschakelen
008	Hook-helpers via require(${__hooks}/utils.js)	De JSVM draait elke hook-callback als geïsoleerd programma; top-level functies zijn níet in scope op call-time
009	createRule: '@request.context = "oauth2"' op team_members	PocketBase past de createRule toe op de OAuth2-sign-up (eerste login maakt het record aan); null blokkeerde élke eerste login met 403 (issue #22). De context-rule staat alléén de OAuth2-flow toe — anonieme REST-creates blijven geweigerd
010	Claims uit het Entra id_token (userInfoURL: "") + UPN-fallback voor e-mail	Graph /oidc/userinfo geeft géén email-claim voor accounts zonder mail-attribuut → 400 bij eerste login (issue #24). Het id_token bevat altijd preferred_username (UPN = primair e-mailadres bij Respellion); entra_oidc.pb.js gebruikt die als fallback (regex-guard tegen guest-UPN's) en logt gefaalde OAuth2-pogingen naar de containerlog
011	updateRule: '(@request.auth.id = id && @request.body.role:isset = false) || @request.auth.role = "admin"', deleteRule: '@request.auth.role = "admin"'	TeamManager-rosterbeheer werkt nu voor app-admins (issue #27). De role:isset-guard sluit tegelijk de privilege-escalatie waarbij een gebruiker zijn eigen role naar admin kon patchen; onboarding raakt role niet en blijft self-service

Bestanden

Bestand	Rol
pb_migrations/1000000000_baseline_ledger_sync.js	Detecteert een out-of-band geprovisionede DB (schema bestaat, _migrations-ledger leeg) en markeert de historische migraties als applied, zodat de replay niet crasht (issue #18).
pb_migrations/1781000000_team_members_to_auth.js	Converteert relation-velden naar text (data blijft behouden), dropt de oude PIN-collection en maakt team_members als auth-collection. Idempotent; provider wordt alleen als fast-path meegenomen als de env al aanwezig is.
pb_migrations/1781000001_tighten_api_rules.js	Zet alle niet-systeem-collecties op @request.auth.id != "".
pb_migrations/1781000002_allow_oauth2_signup.js	Zet createRule = '@request.context = "oauth2"' op reeds-gemigreerde omgevingen (issue #22).
pb_migrations/1781000003_team_members_admin_rules.js	Admin-rosterbeheer + role-escalatie-guard op reeds-gemigreerde omgevingen (issue #27).
pb_hooks/entra_oidc.pb.js	Reconcilieert de OIDC-provider vanuit ENTRA_* env bij elke start + cron-tick (compare-before-save).
pb_hooks/utils.js	Gedeelde helpers (resolveRole, reconcileEntraOidc) — per callback binnenhalen via require().
pb_hooks/team_members.pb.js	Auto-provisioning (role, enrollment_status, naam-fallback) + admin-rol re-sync.
src/lib/azureAuth.js	Canonieke, unit-geteste helpers (OIDC_PROVIDER, resolveRole, parseAdminEmails, deriveName).
src/store/AppContext.jsx	loginWithAzure() / logout() op basis van pb.authStore + authRefresh().
src/pages/Login.jsx	"Sign in with Microsoft"-scherm (geen dropdown/PIN).
src/components/admin/TeamManager.jsx	Roster-beheer: rol wijzigen + verwijderen (geen aanmaken/PIN).

De rol-/allowlist-logica bestaat tweemaal: canoniek in src/lib/azureAuth.js (met tests) en herhaald in pb_hooks/team_members.pb.js (PocketBase JSVM kan de module niet importeren). Houd ze in sync.

Configuratie (environment)

Gerenderd in .env door de Ansible deploy-playbooks en doorgegeven aan de pocketbase-learning-container:

Variabele	Betekenis
ENTRA_TENANT_ID	Entra tenant-id (of common).
ENTRA_CLIENT_ID	App-registration client-id.
ENTRA_CLIENT_SECRET	App-registration client-secret.
ENTRA_ADMIN_EMAILS	Komma-gescheiden e-mail-allowlist die role=admin krijgt, bv. rve@respellion.nl,admin@respellion.nl.

Ansible-variabelen (vault): entra_tenant_id, entra_client_id, entra_client_secret, entra_admin_emails.

Entra App Registration (eenmalig, buiten de codebase)

1. Redirect-URI (Web): https://<host>/api/oauth2-redirect
   • Labs: https://learning-platform.labs.respellion.tech/api/oauth2-redirect
   • Lokaal dev: http://localhost:8090/api/oauth2-redirect (PB-origin)
2. API permissions / scopes: openid, email, profile.
3. Genereer een client-secret en zet de waarden in de Ansible-vault.

Uitbreidingspunten

• Silent SSO (geen tweede klik): als bevestigd is dat de perimeter veilige, niet-spoofbare identity-headers doorstuurt, kan een PocketBase-route die headers vertrouwen en direct een token minten (ADR-004-alternatief).
• Least-privilege rules: schrijf/verwijder op de knowledge-authoring-collecties (topics, relations, content, sources, question_bank, curriculum_versions) verder beperken tot @request.auth.role = "admin". Let op: micro_learnings en theme_sessions worden door reguliere users geschreven (generate-then-cache). Vereist runtime-verificatie.
• Rol op Entra group-claims i.p.v. e-mail-allowlist (aanpassing in pb_hooks/team_members.pb.js + src/lib/azureAuth.js).

Bekende aandachtspunten / go-live

• De OIDC-popup is een top-level navigatie naar login.microsoftonline.com; de bestaande Caddy-CSP (connect-src) raakt dit niet. Verifieer alsnog bij de eerste deploy.
• Verweesde voortgangsrecords van verwijderde (pre-Azure) users zijn acceptabel: zonder geldig Entra-account kan niemand inloggen, dus die records zijn onbereikbaar.
• Credential-rotatie: update de ENTRA_* secrets (Gitea → Ansible .env) en herstart/redeploy — pb_hooks/entra_oidc.pb.js reconcilieert de provider automatisch bij elke start en elke cron-minuut. Geen handmatige re-apply meer.
• Migratiebestanden nooit hernoemen nadat ze ergens applied zijn — de _migrations-ledger is filename-based; hernoemen triggert een re-apply.
• De deploy-playbooks bevatten een health-gate: als PocketBase na de deploy niet healthy wordt, faalt de pipeline zichtbaar en print hij de containerlogs (issue #18 bleef 2 weken onzichtbaar doordat de deploy "groen" was).