Przejdź do głównej zawartości
XOOPS 2.7 Docs

ADR-007: Wdrożenie uwierzytelniania dwuskładnikowego

Status

Dział zatytułowany „Status”

Proposed

Kontekst

Dział zatytułowany „Kontekst”

XOOPS potrzebuje zwiększonego bezpieczeństwa dla uwierzytelniania użytkownika. Uwierzytelnianie dwuskładnikowe (2FA) zapewnia dodatkową warstwę bezpieczeństwa poza hasłami, chroniąc konta nawet jeśli hasła są skompromitowane.

Kluczowe rozważania:

  • Wsteczna kompatybilność z istniejącym uwierzytelnianiem
  • Obsługa wielu metod 2FA
  • Doświadczenie użytkownika podczas konfiguracji i logowania
  • Mechanizmy odzyskiwania w przypadku utraty urządzeń
  • Integracja z istniejącym systemem uprawnień

Decyzja

Dział zatytułowany „Decyzja”

Będziemy wdrażać TOTP (Time-based One-Time Password) jako podstawową metodę 2FA z obsługą kodów zapasowych.

Podejście wdrażania

Dział zatytułowany „Podejście wdrażania”
sequenceDiagram
    participant U as Użytkownik
    participant X as XOOPS
    participant T as Biblioteka TOTP
    participant D as Baza danych


    U->>X: Zaloguj się hasłem
    X->>D: Waliduj hasło
    D-->>X: Hasło ważne
    X->>D: Sprawdź czy 2FA jest włączone
    D-->>X: 2FA wymagane
    X->>U: Poproś kod 2FA
    U->>X: Prześlij kod TOTP
    X->>T: Waliduj kod
    T-->>X: Kod ważny
    X->>U: Logowanie udane

Database Schema

Dział zatytułowany „Database Schema”
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 Interface

Dział zatytułowany „Service Interface”
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

Dział zatytułowany „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);
    }
}

Konsekwencje

Dział zatytułowany „Konsekwencje”

Pozytywne

Dział zatytułowany „Pozytywne”
  • Znacznie lepsze bezpieczeństwo konta
  • Kompatybilność TOTP zgodna ze standardem branżowym (Google Authenticator, Authy itp.)
  • Kody zapasowe zapobiegają blokowaniu konta
  • Opcjonalnie na użytkownika - nie wymusza przyjęcia
  • Middleware PSR-15 pozwala na czystą integrację

Negatywne

Dział zatytułowany „Negatywne”
  • Dodatkowy krok logowania wpływa na doświadczenie użytkownika
  • Użytkownicy muszą zarządzać aplikacjami uwierzytelniającymi
  • Utracone urządzenia wymagają procesu odzyskiwania
  • Dodatkowa pamięć bazy danych i zapytania
  • Wymaga zależności biblioteki kryptograficznej

Ścieżka migracji

Dział zatytułowany „Ścieżka migracji”
  1. Dodaj tabelę bazy danych dla danych 2FA
  2. Wdrożyć usługę TOTP z zależnością biblioteki
  3. Dodaj middleware do łańcucha uwierzytelniania
  4. Utwórz interfejs konfiguracji i weryfikacji
  5. Opcja administracyjna wymagająca 2FA dla określonych grup

Rozważane alternatywy

Dział zatytułowany „Rozważane alternatywy”

OTP oparte na SMS

Dział zatytułowany „OTP oparte na SMS”

Odrzucone ze względu na:

  • Podatności na wymianę SIM
  • Koszt bramy SMS
  • Złożoność weryfikacji numeru telefonu
  • Obawy dotyczące prywatności

Klucze zabezpieczeń sprzętowego (WebAuthn)

Dział zatytułowany „Klucze zabezpieczeń sprzętowego (WebAuthn)”

Odłożone na przyszły ADR:

  • Bardziej złożone wdrażanie
  • Historycznie ograniczona obsługa przeglądarki
  • Wyższy koszt dla użytkownika
  • Mogą być dodane wraz z TOTP później

OTP oparte na poczcie elektronicznej

Dział zatytułowany „OTP oparte na poczcie elektronicznej”

Odrzucone ze względu na:

  • Kompromis konta e-mail pokonuje cel
  • Opóźnienia w dostarczaniu wpływają na UX
  • Problemy z filtrem antyspamowym

Odwołania

Dział zatytułowany „Odwołania”