-
Notifications
You must be signed in to change notification settings - Fork 0
Authentifizierung und Rechte
Die API authentifiziert Benutzer gegen die Schichtplaner5-Benutzertabelle
(5USER.DBF) und kombiniert ein dreistufiges Rollenmodell mit den granularen
Schreibrechten des Originals.
POST /api/auth/login prüft Benutzername/Passwort gegen die Benutzertabelle.
Bei Erfolg:
- wird ein signiertes JWT (HS256, mit Session-ID-Claim) erzeugt und im Response-Body zurückgegeben,
- die Session zusätzlich serverseitig registriert — Sessions können damit einzeln widerrufen werden (Logout, Passwortwechsel, Benutzer-Löschung),
- ein HttpOnly-Cookie
sp5_tokengesetzt (SameSite=strict;Secureaußerhalb des Dev-Modus).
Hat der Benutzer 2FA aktiviert, antwortet der Login ohne totp_code mit
requires_2fa: true — der Client wiederholt den Login mit Code (zweistufig).
Bei jedem Request wird das Token in dieser Priorität gesucht:
-
X-Auth-Token-Header -
sp5_token-Cookie (HttpOnly) -
?token=-Query-Parameter — nur für Endpoints, die keine Header erlauben (SSE/EventSource, iCal-Feeds)
Alle /api/*-Routen außer den öffentlichen (Health, Metrics, Version, Login,
Error-Reports, iCal-Feed-Token-URLs) verlangen ein gültiges Token — sonst 401.
| Mechanismus | Verhalten (Default) |
|---|---|
| Rate-Limit Login | 5 Versuche/Minute (RATE_LIMIT_LOGIN) |
| Brute-Force-Lockout | 5 Fehlversuche → 15 Minuten Sperre pro Benutzername (BRUTE_FORCE_MAX_ATTEMPTS / BRUTE_FORCE_LOCKOUT_MINUTES) |
| Token-Laufzeit | 8 Stunden (TOKEN_EXPIRE_HOURS) |
| Session-Limit | max. 10 Sessions pro Benutzer, älteste wird verdrängt (MAX_SESSIONS_PER_USER) |
| Passwort-Policy | min. 8 Zeichen, Großbuchstabe und Ziffer erforderlich (SP5_PW_MIN_LENGTH, SP5_PW_REQUIRE_UPPER, SP5_PW_REQUIRE_DIGIT) |
| Audit-Log | Alle sicherheitsrelevanten Aktionen als JSON-Lines (SP5_AUDIT_LOG) |
⚠️ In Produktion unbedingtSECRET_KEY(bzw.SP5_JWT_SECRET) setzen — ohne konfiguriertes Secret wird pro Prozess ein Zufallswert erzeugt und alle Tokens verfallen bei jedem Neustart. Siehe Konfiguration.
Jeder Benutzer kann 2FA selbst aktivieren:
-
POST /api/auth/2fa/setup— liefert TOTP-Secret und QR-Code (base64-PNG) für Authenticator-Apps. -
POST /api/auth/2fa/enable— verifiziert den ersten Code, aktiviert 2FA und gibt einmalige Backup-Codes zurück. - Ab jetzt ist der Login zweistufig (
requires_2fa).
Weitere Routen: GET /api/auth/2fa/status, POST /api/auth/2fa/disable
(mit Passwort-Bestätigung) und POST /api/auth/2fa/admin-disable/{user_id}
(Admin-Reset bei Geräteverlust).
Anleitung aus Anwendersicht: App-Wiki → Zwei-Faktor-Authentifizierung.
Drei Rollen in aufsteigender Hierarchie:
| Rolle | Stufe | Typische Rechte |
|---|---|---|
| Leser | 1 | Lesen aller Ansichten, Self-Service (eigene Wünsche, Tauschanträge, Abwesenheitsanträge) |
| Planer | 2 | zusätzlich Schreiben im Dienstplan, Abwesenheiten, Genehmigungen, Berichte verwalten |
| Admin | 3 | zusätzlich Stammdaten-Verwaltung, Benutzer, Backups, Importe, Webhooks, Systemeinstellungen |
Eine höhere Rolle schließt die niedrigeren ein. Welche Rolle eine Route mindestens verlangt, zeigt die Endpunkt-Referenz (Legende P/L/PL/A).
Benutzer werden über GET/POST /api/users, PUT/DELETE /api/users/{id}
verwaltet (nur Admin) — oder bequem über die
Benutzerverwaltung der Hauptanwendung.
Zusätzlich zur Rolle erzwingt jede Schreibroute die granularen Rechte aus
dem Benutzerdatensatz der Original-Benutzertabelle. GET /api/auth/me liefert
sie als permissions-Objekt (Schlüssel kleingeschrieben: wduties,
wabsences, …), sodass Clients Bedienelemente passend ein-/ausblenden können.
Neben den Schreibrechten enthält das Objekt auch die Anzeige-Flags showabs,
shownotes, showstats sowie backup aus dem Benutzerdatensatz — diese sind
für Clients gedacht und werden serverseitig nicht als Routenschutz erzwungen.
| Flag | Erlaubt Schreiben von … |
|---|---|
WDUTIES |
Dienstplan-Einträgen (Schichten) |
WABSENCES |
Abwesenheiten |
WOVERTIMES |
Stundenbuchungen (Zeitkonto) |
WNOTES |
Notizen |
WDEVIATION |
Einsatzplan-Abweichungen |
WCYCLEASS |
Schichtzyklus-Zuweisungen |
WSWAPONLY |
Diensttausch (auch ohne WDUTIES) |
ADDEMPL |
Anlegen neuer Mitarbeiter (Opt-in, siehe unten) |
WPAST |
Schreiboperationen mit Datum in der Vergangenheit |
-
Mindestrolle Planer + Flag: Eine Schreibroute verlangt die Rolle
Planer(oder höher) und eines der für sie deklarierten W*-Flags. - Fehlendes Flag gilt als gewährt: Ist ein W*-Flag im Benutzerdatensatz nicht gesetzt (leer/unbekannt), wird es als erlaubt behandelt — Bestandsdaten ohne gepflegte Rechte bleiben so funktionsfähig.
- Admin hat immer alle Rechte.
-
ADDEMPList die Ausnahme (Opt-in): Mitarbeiter anlegen dürfen nur Benutzer mit explizit gesetztem Flag — oder Admins. Anders als bei den W*-Flags reicht ein fehlendes Flag hier nicht. -
Diensttausch: Für
POST /api/schedule/swapgenügtWDUTIESoderWSWAPONLY.
WPAST=0 blockiert jede Schreiboperation mit einem Datum in der
Vergangenheit, einschließlich der Sammelrouten:
-
POST /api/schedule/bulk(je Eintrag),/bulk-group,/copy-week,/swap(je Datum), - Einsatzplan-Schreibrouten (
POST/PUT/DELETE /api/einsatzplan*, Abweichungen), - Buchungs-Schreibrouten (
POST/DELETE /api/bookings*).
Bei ID-basierten Updates/Deletes zählt das Datum des gespeicherten Datensatzes, nicht das Request-Datum.
Das eingebaute Admin-Konto und der letzte verbleibende Administrator
können weder herabgestuft noch gelöscht werden — ein System ohne Admin-Zugang
kann so nicht entstehen.
# Login
curl -s -X POST http://localhost:8000/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username": "Admin", "password": "<passwort>"}'
# → {"ok": true, "token": "<JWT>", "user": {...}, "expires_at": ...}
# Authentifizierter Request per Header
curl -s http://localhost:8000/api/v1/auth/me -H 'X-Auth-Token: <JWT>'
# → {..., "permissions": {"wduties": true, "wpast": false, ...}}- Endpunkt-Referenz — Rollen-Anforderungen je Route
- Konfiguration — Secrets, Rate-Limits, Passwort-Policy
- App-Wiki → Benutzerverwaltung
- App-Wiki → Security
Home — Startseite
- Installation-und-Betrieb — PyPI, Docker, Compose, Health & Metrics
- Endpunkt-Referenz — alle 313 Routen im Überblick
- Authentifizierung-und-Rechte — Login, JWT, 2FA, Rollen & Rechte
- Konfiguration — Environment-Variablen
- Berichte-und-Exporte — Exporte, Formate, Scheduled Reports
- Entwicklung — Setup, Tests, Releases