deploy

docs/admin.md

@@ -1,5 +1,9 @@
 # Adminbereich
 
+Die Systemrolle `ADMIN` kann aus den getrennten Quellen `MANUAL` und `OIDC` wirksam sein. Die
+Benutzerverwaltung zeigt die Herkunft; das externe Mapping ist nur über die Umgebung konfigurierbar.
+Siehe [Administratoren über OIDC](oidc-administrator.md).
+
 Der Adminbereich liegt im Frontend unter `/admin` und verwendet dieselbe
 serverseitige Authentifizierung, CSRF-Pruefung und Permission-Logik wie die
 restliche Anwendung. Angular blendet Navigation und Aktionen nur fuer passende

docs/configuration.md

@@ -1,5 +1,8 @@
 # Konfiguration
 
+Die globale Administratorrolle wird serverseitig über `OIDC_ADMIN_ROLE` und `OIDC_ROLES_CLAIM`
+synchronisiert. Details stehen unter [Administratoren über OIDC](oidc-administrator.md).
+
 Die Runtime-Konfiguration wird ueber Umgebungsvariablen geladen und mit Zod in
 `apps/backend/src/config/env.ts` validiert. `.env.example` ist die Referenz fuer
 lokale Entwicklung und Deployment-Vorlagen.

docs/oidc-administrator.md

@@ -0,0 +1,63 @@
+# Administratoren über OIDC
+
+HausPilot synchronisiert die globale lokale Systemrolle mit dem stabilen Schlüssel `ADMIN` bei
+jedem erfolgreichen vollständigen OIDC-Login. Die Reihenfolge der Anmeldungen spielt keine Rolle;
+der frühere Mechanismus „erster Benutzer wird Administrator“ existiert nicht mehr.
+
+## Konfiguration
+
+```env
+OIDC_ADMIN_ROLE=hauspilot-admin
+OIDC_ROLES_CLAIM=roles
+OIDC_ROLE_MATCH_CASE_SENSITIVE=true
+```
+
+`OIDC_ADMIN_ROLE` enthält den exakten externen Rollennamen und hat bewusst keinen Standardwert.
+`OIDC_ROLES_CLAIM` unterstützt einfache und verschachtelte Pfade wie `roles`, `groups`,
+`realm_access.roles` oder `resource_access.hauspilot.roles`. Der Claim darf ein String oder ein
+Array aus Strings sein; Leerwerte und Duplikate werden entfernt.
+
+Ist `OIDC_ADMIN_ROLE` leer oder nicht gesetzt, protokolliert der Start eine Warnung. HausPilot
+fügt dann keine OIDC-Administratorzuweisung hinzu und entfernt auch keine bestehende. Ein gesetztes
+`OIDC_ADMIN_ROLE` ohne gültiges `OIDC_ROLES_CLAIM` führt zu einem Startfehler.
+
+## Synchronisierung und Fail-Safe-Verhalten
+
+Nach Signatur-, Issuer-, Audience- und Nonce-Prüfung des ID Tokens werden dessen Claims mit der
+subject-geprüften UserInfo zusammengeführt. Enthält der lesbare Rollenclaim `OIDC_ADMIN_ROLE`, wird
+die Quelle `OIDC` für die lokale Administratorrolle sichergestellt. Fehlt die Rolle in einer
+gültigen Rollenliste, wird nur diese OIDC-Quelle entfernt.
+
+Fehlt der konfigurierte Claim technisch oder hat er ein ungültiges Format, wird keine Zuweisung
+verändert und der Login fail-safe abgebrochen. Tokens und vollständige Claims werden weder
+protokolliert noch zusätzlich gespeichert. Die Synchronisierung geschieht vor dem Erzeugen der
+Session. Es gibt derzeit keinen Token-Refresh mit erneuter Claim-Validierung; Änderungen werden
+beim nächsten vollständigen Login wirksam.
+
+## Quellenmodell und Migration
+
+`user_role_assignments` speichert für Benutzer, Rolle und Quelle eine eindeutige Zuweisung mit den
+Quellen `MANUAL`, `OIDC` und `SYSTEM`. `user_roles` bleibt die effektive Projektion für bestehende
+Berechtigungsabfragen. Die Migration übernimmt alle vorhandenen Zuordnungen als `MANUAL`; keine
+bestehende Administratorrolle wird rückwirkend als OIDC interpretiert. Ein Unique Constraint
+verhindert doppelte Quellen bei parallelen Logins.
+
+Die Benutzerverwaltung zeigt die Herkunft an. Eine reine OIDC-Zuweisung lässt sich lokal nicht
+entfernen; die externe Rolle muss im Identity Provider entzogen werden. Bei `MANUAL + OIDC` kann
+die manuelle Quelle separat entfernt werden. Projektrollen und der Zugriff auf private Projekte
+bleiben unverändert.
+
+## Erstkonfiguration und Recovery
+
+1. Im Identity Provider eine Adminrolle anlegen und mindestens zwei Recovery-fähigen Benutzern geben.
+2. `OIDC_ADMIN_ROLE` und `OIDC_ROLES_CLAIM` in der Serverumgebung setzen.
+3. Migrationen kontrolliert mit `npm run migration:run` ausführen und die Anwendung neu starten.
+4. Benutzer vollständig neu anmelden.
+
+Änderungen des Rollennamens werden pro Benutzer beim nächsten Login wirksam. Wird die Variable
+geleert, bleiben bestehende OIDC-Zuweisungen bewusst erhalten. Für Notfälle kann eine kontrollierte
+Datenbankoperation oder ein separater, nicht öffentlicher CLI-Prozess eine `MANUAL`-Zuweisung
+setzen. Es gibt keine öffentliche Recovery-Route und keinen First-User-Fallback.
+
+Tatsächliche Änderungen werden als `OIDC_ADMIN_ASSIGNED` beziehungsweise `OIDC_ADMIN_REMOVED`
+auditiert; der externe Rollenname darf erscheinen, niemals Tokens oder vollständige Claims.

docs/security.md

@@ -1,5 +1,9 @@
 # Security-Modell
 
+Globale Administratorrechte werden beim Login ausschließlich aus serverseitig validierten
+OIDC-Claims synchronisiert. Es gibt keine browserseitige Rollenübermittlung und keinen
+First-User-Admin-Fallback. Details: [Administratoren über OIDC](oidc-administrator.md).
+
 Das Boilerplate trennt Browser, Backend und Identity Provider strikt. Der Browser
 bekommt keine OIDC-Tokens. Das Backend ist fuer Authentifizierung,
 Autorisierung, CSRF und Session-Verwaltung verbindlich.