ADR-007: Two-Factor-Authentication Implementierung

Status

Proposed

Context

XOOPS benötigt verbesserte Sicherheit für Benutzerauthentifizierung. Two-Factor Authentication (2FA) bietet eine zusätzliche Sicherheitsebene über Passwörter hinaus und schützt Konten, selbst wenn Passwörter kompromittiert sind.

Wichtige Überlegungen:

• Abwärtskompatibilität mit existierender Authentifizierung
• Unterstützung mehrerer 2FA-Methoden
• Benutzererlebnis während Setup und Login
• Recovery-Mechanismen für verlorene Geräte
• Integration mit existierendem Permission-System

Decision

Wir werden TOTP (Time-based One-Time Password) als primäre 2FA-Methode mit Unterstützung für Backup-Codes implementieren.

Implementierungs-Ansatz

sequenceDiagram
    participant U as User
    participant X as XOOPS
    participant T as TOTP Library
    participant D as Database

    U->>X: Login with password
    X->>D: Validate password
    D-->>X: Password valid
    X->>D: Check 2FA enabled
    D-->>X: 2FA required
    X->>U: Request 2FA code
    U->>X: Submit TOTP code
    X->>T: Validate code
    T-->>X: Code valid
    X->>U: Login successful

Datenbankschema

CREATE TABLE `{PREFIX}_users_2fa` (
    `user_id` INT(11) NOT NULL,
    `secret` VARCHAR(32) NOT NULL,
    `enabled` TINYINT(1) DEFAULT 0,
    `backup_codes` TEXT,
    `last_used` INT(11),
    `created` INT(11) NOT NULL,
    PRIMARY KEY (`user_id`),
    FOREIGN KEY (`user_id`) REFERENCES `{PREFIX}_users`(`uid`)
);

Service-Schnittstelle

interface TwoFactorAuthInterface
{
    public function enable(int $userId): TwoFactorSetup;
    public function disable(int $userId): void;
    public function verify(int $userId, string $code): bool;
    public function generateBackupCodes(int $userId): array;
    public function isEnabled(int $userId): bool;
}

Middleware-Integration

class TwoFactorMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        $session = $request->getAttribute('session');

        if ($session->has('pending_2fa_user_id')) {
            // User needs to complete 2FA
            if ($this->isVerificationRequest($request)) {
                return $handler->handle($request);
            }
            return new RedirectResponse('/2fa/verify');
        }

        return $handler->handle($request);
    }
}

Consequences

Positiv

• Significantly improved account security
• Industry-standard TOTP compatibility (Google Authenticator, Authy, etc.)
• Backup codes prevent account lockout
• Optional per-user - doesn’t force adoption
• PSR-15 middleware allows clean integration

Negativ

• Additional login step impacts user experience
• Users must manage authenticator apps
• Lost devices require recovery process
• Additional database storage and queries
• Requires cryptographic library dependency

Migration Path

1. Add database table for 2FA data
2. Implement TOTP service with library dependency
3. Add middleware to authentication chain
4. Create setup and verification UI
5. Admin option to require 2FA for specific groups

Alternatives Considered

SMS-basierte OTP

Abgelehnt aufgrund von:

• SIM-Swap-Anfälligkeit
• Kosten des SMS-Gateways
• Telefonnummer-Verifizierungs-Komplexität
• Datenschutz-Bedenken

Hardware-Sicherheitsschlüssel (WebAuthn)

Aufgeschoben für zukünftiges ADR:

• Komplexere Implementierung
• Limitierte Browser-Unterstützung bislang
• Höhere Benutzer-Kosten
• Könnte später neben TOTP hinzugefügt werden

Email-basierte OTP

Abgelehnt aufgrund von:

• Email-Account-Kompromittierung besiegt Zweck
• Delivery-Verzögerungen wirken sich auf UX aus
• Spam-Filter-Probleme

References

• RFC 6238 - TOTP
• Google Authenticator Key Format
• ../../02-Core-Concepts/Security/Security-Best-Practices - Security guidelines
• ../../02-Core-Concepts/Users-Permissions/Authentication - Auth system documentation