wiki/b-reference/platform/authentication.md

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