# 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=groups 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. Der konfigurierte Claim muss vom Provider fuer die angeforderten Scopes geliefert werden. Fuer Provider, die Gruppen ueber den standardnahen `groups`-Scope in UserInfo bereitstellen, gilt: ```env OIDC_SCOPES=openid profile email groups OIDC_ROLES_CLAIM=groups ``` Das Backend liest den `userinfo_endpoint` aus der OIDC-Discovery und ruft ihn serverseitig mit dem Access-Token auf. Der Access-Token und die vollstaendigen Claims werden nicht an den Browser gegeben oder protokolliert. 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.