flat-pilot/docs/oidc-administrator.md

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

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:

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.