flat-pilot/docs/admin.md

Adminbereich

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 Permissions ein; verbindlich prueft immer das Backend.

Permissions

Die administrativen Permissions sind fest in apps/backend/src/roles/permissions.ts definiert:

• users.read: Benutzer anzeigen, suchen und filtern
• users.manage: Benutzer aktivieren, deaktivieren und Rollen zuweisen
• roles.read: Rollen und Permissions anzeigen
• roles.manage: Rollen anlegen, bearbeiten und loeschen
• sessions.manage: Sessions anderer Benutzer anzeigen und beenden
• audit.read: administratives Audit-Log anzeigen

Benutzer haben keine direkten Permissions. Effektive Permissions werden aus allen Rollen abgeleitet. Rollen- und Benutzerverwaltung laufen ueber Services; Controller greifen nicht direkt auf TypeORM-Repositories zu.

Systemrollen

Es gibt mindestens die Systemrollen admin und user.

• admin ist geschuetzt, nicht loeschbar und muss administrative Permissions behalten.
• user ist geschuetzt, nicht loeschbar und Standardrolle fuer neue Benutzer.
• Eigene Rollen koennen angelegt, umbenannt, geloescht und mit bekannten Permissions versehen werden.

Eine Rolle kann nur geloescht werden, wenn sie keinem Benutzer mehr zugewiesen ist. Andernfalls antwortet die API mit ROLE_STILL_ASSIGNED.

Letzter aktiver Administrator

Die Anwendung darf nie ohne aktiven Administrator enden. Sicherheitskritische Aktionen laufen transaktional und halten einen MySQL-Lock business_app_admin_integrity:

• Benutzer deaktivieren
• Rollen eines Benutzers aendern
• Adminrolle entfernen
• Adminrolle in ihren Permissions veraendern
• Rolle loeschen

Wenn eine Aktion den letzten aktiven Administrator entfernen wuerde, antwortet die API mit HTTP 409 und LAST_ACTIVE_ADMIN_REQUIRED.

Benutzerstatus und Sessions

Benutzer werden weiterhin ausschliesslich ueber OIDC angelegt. Name und E-Mail kommen vom Identity Provider und sind im Adminbereich nicht editierbar.

Beim Deaktivieren wird der Benutzer sofort inaktiv gesetzt und alle aktiven Sessions des Benutzers werden widerrufen. Neue OIDC-Logins deaktivierter Benutzer werden trotz erfolgreicher IdP-Authentifizierung abgewiesen. Beim erneuten Aktivieren darf sich der Benutzer wieder anmelden; alte Sessions werden nicht wiederhergestellt.

Admin-Session-Endpunkte geben nur eine sichere, gekuerzte Session-Referenz, Zeitpunkte, User-Agent, IP-Annaeherung und Status zurueck. Tokens und rohe Session-Secrets werden nie ausgegeben.

API-Endpunkte

Benutzer:

• GET /api/admin/users
• GET /api/admin/users/:id
• PATCH /api/admin/users/:id/deactivate
• PATCH /api/admin/users/:id/activate
• POST /api/admin/users/:id/roles/:roleId
• DELETE /api/admin/users/:id/roles/:roleId
• GET /api/admin/users/:id/sessions
• DELETE /api/admin/users/:userId/sessions/:sessionId
• DELETE /api/admin/users/:id/sessions

Rollen:

• GET /api/admin/roles
• GET /api/admin/roles/:id
• POST /api/admin/roles
• PUT /api/admin/roles/:id
• DELETE /api/admin/roles/:id

Audit:

• GET /api/audit-log

Audit-Log

Administrative Aenderungen werden auditierbar protokolliert, darunter:

• USER_ACTIVATED
• USER_DEACTIVATED
• USER_ROLE_ASSIGNED
• USER_ROLE_REMOVED
• ROLE_CREATED
• ROLE_UPDATED
• ROLE_DELETED
• ROLE_PERMISSIONS_UPDATED
• SESSION_REVOKED
• ALL_USER_SESSIONS_REVOKED

Gespeichert werden fachliche IDs, Request-ID und minimale Metadaten. Tokens, Secrets und vollstaendige Sessiondaten werden nicht geloggt.

Migration

Die Admin-Erweiterung fuegt roles.description hinzu. Vor dem Deployment muss die Migration ausgefuehrt werden:

npm run migration:run

Der normale App-Start fuehrt Migrationen weiterhin nicht automatisch aus, sondern meldet fehlende Migrationen ueber die Readiness-Pruefung.