129 lines
6 KiB
Markdown
129 lines
6 KiB
Markdown
<!-- status: canonical -->
|
|
<!-- lastReviewed: 2026-06-11 -->
|
|
<!-- verifiedAgainst: platform-core modules/auth/*, modules/routes/routeSecurity*.py, modules/routes/routeMfa.py -->
|
|
|
|
# Authentifizierung & Session-Management
|
|
|
|
## Uebersicht
|
|
|
|
PORTA verwendet ein **hybrides JWT + Server-Side Token-Registry**-Modell. Jeder Login erzeugt ein JWT-Paar (Access + Refresh); die Token-IDs werden serverseitig in PostgreSQL gespeichert, um Revocation und Session-Management zu ermoeglichen.
|
|
|
|
## Login-Methoden
|
|
|
|
| Methode | Route | Provider |
|
|
|---------|-------|----------|
|
|
| Lokal (E-Mail/Passwort) | `POST /api/local/login` | Eigene DB |
|
|
| Microsoft (Entra ID) | `GET /api/msft/auth/login` | Azure AD OAuth2 |
|
|
| Google | `GET /api/google/auth/login` | Google OAuth2 |
|
|
|
|
## Token-Architektur
|
|
|
|
### Access Token
|
|
- **Algorithmus:** HS256
|
|
- **Lebensdauer:** Konfigurierbar via `APP_TOKEN_EXPIRY` (Default: 300 Minuten)
|
|
- **Claims:** `sub`, `userId`, `authenticationAuthority`, `jti`, `sid` (Session-ID), `exp`
|
|
- **Transport:** httpOnly Cookie `auth_token` (primaer) oder `Authorization: Bearer` (API-Clients)
|
|
|
|
### Refresh Token
|
|
- **Lebensdauer:** Konfigurierbar via `APP_REFRESH_TOKEN_EXPIRY` (Default: 7 Tage)
|
|
- **Claims:** Wie Access + `type: "refresh"`
|
|
- **Transport:** httpOnly Cookie `refresh_token`
|
|
|
|
### Cookie-Policy
|
|
- **HTTPS (Prod):** `Secure=True`, `SameSite=None` (Cross-Origin SPA)
|
|
- **HTTP (Dev):** `Secure=False`, `SameSite=Lax`
|
|
- Steuerbar via `APP_COOKIE_SECURE` env-Variable
|
|
|
|
## Multi-Session-Support
|
|
|
|
PORTA erlaubt **parallele Sessions** auf mehreren Geraeten/Browsern gleichzeitig. Ein neuer Login invalidiert bestehende Sessions NICHT.
|
|
|
|
### Regulatorischer Kontext
|
|
- **NIST SP 800-63B (Section 7.1):** Erlaubt explizit mehrere aktive Authenticator-Sessions pro Subscriber. Kein Grund fuer Single-Session-Erzwingung bei korrekt implementierter Revocation.
|
|
- **BSI TR-03107:** Empfiehlt Session-Management mit Monitoring, nicht Single-Session-Zwang.
|
|
- **Praxisstandard:** Microsoft 365, Google Workspace, AWS Console — alle erlauben parallele Sessions.
|
|
|
|
### Sicherheitsgarantien
|
|
- Jede Session hat eine eigene `sessionId` (UUID)
|
|
- Admin kann jede Session einzeln oder alle Sessions eines Users revoken
|
|
- Logout betrifft nur die aktuelle Session (`DELETE /api/local/logout`)
|
|
- Token-DB-Pruefung bei jedem Request: nur Tokens mit aktivem DB-Eintrag sind gueltig
|
|
|
|
## Silent Token Refresh
|
|
|
|
Wenn der Access Token ablaeuft, versucht das Frontend automatisch eine stille Erneuerung via `POST /api/local/refresh`, bevor zum Login umgeleitet wird.
|
|
|
|
### Ablauf
|
|
1. API-Request erhaelt 401
|
|
2. Frontend ruft `POST /api/local/refresh` (sendet `refresh_token` Cookie)
|
|
3. Backend validiert Refresh-JWT + erstellt neuen Access Token
|
|
4. Neuer Access Token wird in DB registriert + als Cookie gesetzt
|
|
5. Originaler Request wird mit neuem Token wiederholt
|
|
|
|
Falls Refresh fehlschlaegt (Token abgelaufen/revoked): Redirect zu `/login`.
|
|
|
|
## MFA (Multi-Faktor-Authentifizierung)
|
|
|
|
### Wann MFA verlangt wird (OR-Logik)
|
|
1. User hat `mfaEnabled=True` (Opt-in)
|
|
2. Mindestens ein Mandat des Users hat `mfaRequired=True`
|
|
3. User ist SysAdmin/PlatformAdmin UND `MFA_REQUIRE_ADMINS=True`
|
|
|
|
### Verfahren
|
|
- **TOTP** (Time-based One-Time Password) via `pyotp`
|
|
- 6 Ziffern, 30-Sekunden-Intervall, Toleranzfenster ±1
|
|
- Secrets verschluesselt gespeichert (AES/Fernet)
|
|
|
|
## Trusted Device (MFA-Skip)
|
|
|
|
Nach erfolgreicher MFA-Verifizierung kann ein Geraet als **vertrauenswuerdig** markiert werden. Fuer die konfigurierte Dauer (Default: 60 Tage) wird MFA auf diesem Geraet uebersprungen.
|
|
|
|
### Regulatorischer Kontext
|
|
- **NIST SP 800-63B (Section 5.2.8):** Erlaubt "remember this device" ausdruecklich unter der Bedingung, dass der Authenticator kryptographisch an den Subscriber gebunden ist.
|
|
- **BSI TR-03107:** Akzeptiert geraetegebundene Vertrauensstellung bei angemessener Laufzeitbegrenzung.
|
|
- **Praxisstandard:** Microsoft ("Don't ask again for 60 days"), Google (trusted device), AWS (remembered device).
|
|
|
|
### Mechanismus
|
|
- httpOnly Cookie `mfa_trusted` mit kryptographisch zufaelligem Token
|
|
- Server-Eintrag in `TrustedDevice`-Tabelle: `id`, `userId`, `trustedUntil`, `userAgent`, `ipAddress`
|
|
- Beim Login: Cookie vorhanden + DB-Eintrag gueltig → MFA uebersprungen
|
|
- Admin oder User kann Trusted Devices jederzeit revoken
|
|
- Automatische Bereinigung abgelaufener Eintraege
|
|
|
|
### Sicherheitsgrenzen
|
|
- Vertrauensdauer auf 60 Tage begrenzt (konfigurierbar)
|
|
- Bei Passwort-Aenderung oder Admin-Revoke: alle Trusted Devices invalidiert
|
|
- Cookie ist geraetegebunden (httpOnly, nicht uebertragbar)
|
|
|
|
## Session-Verwaltung (Admin)
|
|
|
|
Administratoren koennen aktive Sessions und Trusted Devices ueber API-Endpoints verwalten:
|
|
|
|
| Endpoint | Beschreibung |
|
|
|----------|-------------|
|
|
| `GET /api/admin/sessions?userId=X` | Aktive Sessions eines Users |
|
|
| `DELETE /api/admin/sessions/{sessionId}` | Einzelne Session revoken |
|
|
| `DELETE /api/admin/sessions?userId=X` | Alle Sessions eines Users revoken |
|
|
| `GET /api/admin/trusted-devices?userId=X` | Trusted Devices auflisten |
|
|
| `DELETE /api/admin/trusted-devices?userId=X` | Alle Trusted Devices revoken |
|
|
|
|
## Token-Hygiene
|
|
|
|
- Abgelaufene Token-Eintraege werden automatisch bereinigt (Hintergrundtask)
|
|
- Abgelaufene TrustedDevice-Eintraege werden ebenso bereinigt
|
|
- Revoked-Tokens werden fuer Audit-Zwecke 30 Tage aufbewahrt, danach geloescht
|
|
|
|
## Schluessel-Dateien
|
|
|
|
| Datei | Verantwortung |
|
|
|-------|---------------|
|
|
| `modules/auth/jwtService.py` | JWT-Erzeugung, Cookie-Helpers |
|
|
| `modules/auth/authentication.py` | Token-Validierung, `_getUserBase()` |
|
|
| `modules/auth/mfaService.py` | TOTP-Erzeugung/-Verifizierung |
|
|
| `modules/auth/trustedDeviceService.py` | Trusted-Device-Logik |
|
|
| `modules/routes/routeSecurityLocal.py` | Login/Logout/Refresh Endpoints |
|
|
| `modules/routes/routeSecurityMsft.py` | Microsoft OAuth Callback |
|
|
| `modules/routes/routeSecurityGoogle.py` | Google OAuth Callback |
|
|
| `modules/routes/routeMfa.py` | MFA-Setup/-Verify Endpoints |
|
|
| `modules/interfaces/interfaceDbApp.py` | Token-DB-Operationen |
|
|
| `modules/datamodels/datamodelSecurity.py` | Token + TrustedDevice Models |
|