# 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 |