# Admin Auth Security Enhancement Plan

**Status**: Geplant für später (nach Refactoring anderer Module)  
**Ansatz**: Starke Web-Authentifizierung ohne VPN

## Überblick

Erweitert das Auth-Modul für den Admin-Bereich mit mehrschichtiger Web-Authentifizierung. Fokus auf starke Authentifizierung mit MFA, Session-Sicherheit und Rate Limiting.

## Sicherheitsebenen

1. **Obligatorisches MFA (TOTP)** - Zweiter Faktor zwingend erforderlich
2. **Strenge Session-Sicherheit** - Regeneration, IP-Tracking, Timeouts
3. **Rate Limiting & Account Lockout** - Schutz gegen Brute-Force
4. **IP-basierte Einschränkungen** (optional) - Zusätzliche Barriere ohne VPN
5. **Security Headers** - CSRF-Schutz, Secure Cookies, HSTS

## Aktuelle Situation

- Basis-Authentifizierung mit Session-Management vorhanden
- MFA/TOTP-Services existieren (`TotpService`, `MfaService`), aber nicht vollständig integriert
- IP-basierte Einschränkungen existieren (`ProductionSecurityMiddleware`)
- AuthMiddleware ist derzeit deaktiviert
- RouteAuthorizationService existiert, aber nicht konfiguriert

## Implementation Plan

### Phase 1: Auth-Modul Erweiterung

1. **AdminAuthService** erstellen
   - Integration mit bestehendem `AuthenticationService`
   - Admin-spezifische Authentifizierungslogik
   - Session-Management für Admin-Bereich
   - IP-Tracking und Session-Regeneration
   - MFA-Status-Prüfung

2. **MFA-Integration** für Admin-Bereich
   - TOTP als obligatorische zweite Faktor über `MfaService`/`TotpProvider`
   - QR-Code-Generierung für Setup
   - Backup-Codes für Recovery
   - MFA-Enforcement für alle Admin-Routen

3. **Session-Sicherheit** verbessern
   - Session-Regeneration bei Login
   - IP-Konsistenz-Prüfung (warnen bei IP-Wechsel)
   - Session-Timeouts für Admin-Bereich (kürzer als normale Sessions)
   - Session-Fixation-Schutz
   - Secure Cookie-Flags (HttpOnly, Secure, SameSite)

### Phase 2: Route Protection & Authorization

1. **RouteAuthorizationService** aktivieren und konfigurieren
   - Admin-Namespace (`App\Application\Admin\*`) konfigurieren
   - IP-basierte Zugriffskontrolle (optional, aber empfohlen)
   - MFA-Status-Prüfung für alle Admin-Routen

2. **AuthMiddleware** implementieren
   - Integration mit `RouteAuthorizationService`
   - Session-Validierung
   - MFA-Status-Prüfung
   - Redirect zu Login bei fehlender Authentifizierung
   - Redirect zu MFA-Setup bei fehlender MFA-Konfiguration

3. **AdminLoginController** erstellen
   - Login-Formular
   - MFA-Setup-Flow (wenn noch nicht konfiguriert)
   - MFA-Verifizierung nach initialem Login
   - Session-Erstellung
   - Logout-Funktionalität

### Phase 3: Erweiterte Sicherheitsfeatures

1. **IP-basierte Einschränkungen** (Optional, aber empfohlen)
   - Statische IP-Whitelist für Admin-Zugriff
   - CIDR-Notation für IP-Ranges unterstützen
   - Konfigurierbar über Environment-Variablen
   - Integration mit `ProductionSecurityMiddleware`

2. **Rate Limiting** für Admin-Bereich
   - Striktere Limits als für normale User
   - IP-basierte Rate Limits
   - Account-Lockout nach fehlgeschlagenen Versuchen
   - Separate Limits für Login, MFA-Verifizierung

3. **Security Headers**
   - CSRF-Schutz für alle Admin-Formulare
   - Secure Cookies (HTTPS-only)
   - HSTS für Admin-Bereich
   - Content-Security-Policy

## Dateien die erstellt/geändert werden müssen

### Neue Dateien
- `src/Framework/Auth/AdminAuthService.php` - Admin-spezifischer Auth-Service
- `src/Application/Admin/Auth/AdminLoginController.php` - Login-Controller
- `src/Framework/Auth/MfaRequiredException.php` - Exception für fehlende MFA
- `src/Framework/Auth/AdminMfaService.php` - MFA-Service für Admin-Bereich
- `src/Framework/Auth/AdminMfaSetupResult.php` - Result Value Objects
- `src/Framework/Auth/AdminMfaActivationResult.php`
- `src/Framework/Auth/AdminMfaVerificationResult.php`
- `tests/Framework/Auth/AdminAuthServiceTest.php` - Tests
- `tests/Framework/Auth/AdminMfaServiceTest.php` - MFA-Tests

### Zu erweiternde Dateien
- `src/Framework/Http/Middlewares/AuthMiddleware.php` - Vollständige Implementierung
- `src/Framework/Auth/RouteAuthorizationServiceInitializer.php` - Konfiguration aktivieren
- `src/Framework/Auth/AuthenticationService.php` - MFA-Integration
- `src/Framework/Http/Middlewares/ProductionSecurityMiddleware.php` - IP-Whitelist-Erweiterung
- `src/Framework/Config/EnvKey.php` - Environment-Keys hinzufügen

## Konfiguration

### Environment-Variablen
- `ADMIN_MFA_REQUIRED=true` - MFA obligatorisch
- `ADMIN_SESSION_TIMEOUT=1800` - Session-Timeout (30 Min)
- `ADMIN_IP_WHITELIST` - Optionale IP-Whitelist (komma-separiert, CIDR unterstützt)
- `ADMIN_RATE_LIMIT_ATTEMPTS=3` - Strikte Rate Limits
- `ADMIN_ACCOUNT_LOCKOUT_DURATION=3600` - Lockout nach Fehlversuchen (1h)
- `ADMIN_SESSION_REGENERATE_ON_LOGIN=true` - Session-Regeneration
- `ADMIN_CHECK_IP_CONSISTENCY=true` - IP-Wechsel überwachen

### MFA-Integration
- Verwende `MfaService` mit `TotpProvider` (nicht direkt `TotpService`)
- `MfaMethod::TOTP` für TOTP-Authentifizierung
- `MfaSecret`, `MfaChallenge`, `MfaCode` Value Objects verwenden

## Wichtige Hinweise

- **Kein VPN**: Lösung basiert auf starker Web-Authentifizierung ohne VPN
- **MFA obligatorisch**: Alle Admin-Routen erfordern konfigurierte und verifizierte MFA
- **Audit-Logging**: Wird später implementiert, wenn eine vollständige Audit-Lösung im Framework vorhanden ist
- **IP-Whitelist**: Optional, aber empfohlen für Production

## Referenzen

- MFA-Modul: `src/Framework/Mfa/`
- TotpProvider: `src/Framework/Mfa/Providers/TotpProvider.php`
- RouteAuthorizationService: `src/Framework/Auth/RouteAuthorizationService.php`
- ProductionSecurityMiddleware: `src/Framework/Http/Middlewares/ProductionSecurityMiddleware.php`