# ADR-0004: Keycloak/OIDC als alleiniger Identity Provider

* Status: Angenommen
* Datum: 2026-08-17 (nachträglich dokumentiert; Entscheidung war mit Commit `a420ae3` wirksam)

## Kontext und Problemstellung

PROCUREX benötigt Authentifizierung und rollenbasierte Autorisierung für sechs fachliche Rollen
(`ROLE_BUYER`, `ROLE_APPROVER`, `ROLE_SUPPLIER_ADMIN`, `ROLE_FINANCE`, `ROLE_RECEIVING`,
`ROLE_ADMIN`). Frontend (Angular-SPA) und Backend (Spring-Boot-Modul) brauchen ein gemeinsames
Identitätsmodell. `enterprise-infrastructure` betreibt bereits eine zentrale Keycloak-Instanz für alle
angeschlossenen Lernprojekte.

## Entscheidungstreiber

* `enterprise-infrastructure` stellt Keycloak 26.7.0 zentral bereit (siehe Confluence Seite 12) — ein
  projekteigener Identity Provider würde diese Infrastruktur duplizieren.
* Frontend und Backend sollen keine eigene Passwortverwaltung betreiben (kein Session-basiertes
  Login mit projekteigener User-Tabelle).
* Least-Privilege-Anforderung: jeder REST-Endpunkt soll die minimal nötige Rolle durchsetzen.

## Betrachtete Optionen

* Eigene Session-/Passwort-basierte Authentifizierung im Backend.
* Ein einfacher clientseitiger Rollen-Umschalter ohne echtes Login (Mock), wie er in einer
  früheren Ausbaustufe des Frontends existierte.
* Keycloak-Realm `procurex` mit OIDC/JWT, Authorization Code + PKCE im Frontend, Spring Security
  OAuth2 Resource Server im Backend.

## Entscheidung

Keycloak-Realm `procurex` mit zwei Clients: `procurex-frontend` (public, Authorization Code +
PKCE) und `procurex-backend` (Resource Server, Bearer-only). Rollen kommen aus
`realm_access.roles` im JWT. Das Backend validiert Tokens als echter OAuth2 Resource Server
(`procurex-app`, `SecurityConfig`); das Frontend nutzt `angular-oauth2-oidc` für einen echten
Authorization-Code+PKCE-Login statt eines Mock-Rollenumschalters.

## Begründung

* Wiederverwendung der zentralen `enterprise-infrastructure`-Keycloak-Instanz vermeidet einen zweiten Identity
  Provider und hält die Versionsbasis (26.7.0) konsistent mit der restlichen Lernumgebung.
* OIDC/JWT ist der Industriestandard für SPA+Backend-Rollentrennung und macht den
  Autorisierungs-Check im Backend zustandslos (kein Session-Storage nötig).
* Ein echter PKCE-Login statt eines Mock-Umschalters ermöglicht realistische End-to-End-Tests
  (Playwright-Login/Logout, k6 mit echten Keycloak-JWTs über einen dedizierten
  `procurex-loadtest`-Client) statt eines rein UI-seitigen Rollenwechsels ohne Beweiskraft.

## Konsequenzen

* Positiv: live gegen echte Keycloak-Tokens verifiziert — richtige Rolle → Erfolg, falsche Rolle →
  403, kein Token → 401 (siehe `procurex-app/README.md`, Abschnitt „Security“).
* Positiv: derselbe Mechanismus trägt sowohl E2E-Tests (Playwright) als auch Lasttests (k6) ohne
  separate Mock-Infrastruktur.
* Negativ: lokale Entwicklung setzt eine laufende `enterprise-infrastructure`-Keycloak-Instanz voraus; ohne sie
  ist kein Login möglich (kein Offline-Fallback dokumentiert).
* Negativ: Rollenänderungen erfordern eine Anpassung des Realm-Exports
  (`keycloak/procurex-realm-export.json`) statt einer einfachen DB-Migration.

## Weitere Informationen

Siehe Confluence Seite 10 „APIs, Events, Daten und Security“ (CONFIRMED), Abschnitt
„Umsetzungsnachweis Security & Events“, sowie `keycloak/README.md` und
`keycloak/procurex-realm-export.json`.