generated from bastian/boilerplate
76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# 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.
|