2FA Google Authenticator dla PrestaShop — Dokumentacja

Ten przewodnik obejmuje instalację, konfigurację i codzienne użytkowanie modułu 2FA Google Authenticator dla PrestaShop 8 i 9. Moduł dodaje weryfikację 6-cyfrowym kodem (standard TOTP, RFC 6238) po wpisaniu hasła do back-office.

Wymagania wstępne

• PrestaShop 8.0 do 8.2 lub PrestaShop 9.x
• PHP 7.4 minimum (PHP 8.1+ wymagane przez PrestaShop 9)
• Aplikacja TOTP na telefonie każdego pracownika: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, FreeOTP lub dowolna aplikacja zgodna z RFC 6238
• Zegar serwera zsynchronizowany przez NTP (standard na wszystkich nowoczesnych hostingach)

Instalacja

1. W back-office otwórz Moduły → Menedżer modułów.
2. Kliknij Zainstaluj moduł i wybierz plik df2fa.zip pobrany z Twojego konta DataFirefly.
3. Kliknij Zainstaluj. Moduł tworzy swoją tabelę w bazie danych i automatycznie rejestruje kontrolery.

Konfiguracja modułu

Otwórz Moduły → Menedżer modułów → 2FA Google Authenticator → Konfiguruj. Strona zawiera trzy bloki:

Moje konto 2FA

Panel stanu u góry strony pokazuje, czy Twoje własne 2FA jest aktywne, z bezpośrednim przyciskiem do parowania lub zarządzania.

Konfiguracja 2FA

• 2FA obowiązkowe — w trybie wymuszonym każdy pracownik bez skonfigurowanego 2FA jest automatycznie przekierowywany na stronę parowania zaraz po zalogowaniu. W trybie opt-in (domyślnym) w back-office wyświetla się baner przypominający, a każdy pracownik aktywuje 2FA wtedy, kiedy chce.
• Nazwa wystawcy (Issuer) — nazwa wyświetlana w aplikacji TOTP pracowników (domyślnie nazwa sklepu).

Status 2FA pracowników

Tabela wyświetla wszystkich pracowników wraz ze statusem 2FA (aktywne/nieaktywne), datą konfiguracji i przyciskiem Resetuj dla każdego pracownika z aktywnym 2FA.

Parowanie po stronie pracownika

1. Pracownik otwiera stronę parowania: przez link Skonfiguruj moje 2FA w menu użytkownika (prawy górny róg back-office), przez baner przypominający lub automatycznie przy logowaniu, jeśli aktywny jest tryb obowiązkowy.
2. Skanuje wyświetlony kod QR swoją aplikacją TOTP. Kod QR jest generowany lokalnie w przeglądarce — żadne dane nie są wysyłane do zewnętrznej usługi. Jeśli skanowanie jest niemożliwe, sekret można wpisać ręcznie w aplikacji (przycisk Kopiuj).
3. Wpisuje 6-cyfrowy kod wyświetlany przez aplikację, aby potwierdzić parowanie.
4. Wyświetla się wtedy 8 jednorazowych kodów odzyskiwania — to jedyny moment, w którym są widoczne. Pracownik kopiuje je lub drukuje i przechowuje w bezpiecznym miejscu.

Logowanie z 2FA

Po wpisaniu hasła pracownik jest przekierowywany na ekran weryfikacji 2FA i wpisuje bieżący 6-cyfrowy kod ze swojej aplikacji. Weryfikacja pozostaje ważna przez 12 godzin dla sesji: nie trzeba wpisywać kodu na każdej stronie.

Stosowana jest tolerancja dryfu ±30 sekund, aby zniwelować drobne różnice zegara między serwerem a telefonem.

Kody odzyskiwania

Jeśli pracownik nie ma już dostępu do aplikacji TOTP (telefon zgubiony, skradziony, zresetowany):

1. Na ekranie weryfikacji kliknij Użyj kodu odzyskiwania.
2. Wpisz jeden z 8 kodów odzyskiwania (10 znaków).
3. Każdy kod działa tylko raz. Po zalogowaniu wyłącz i ponownie włącz 2FA, aby wygenerować nowe parowanie i nowy zestaw kodów.

Ochrona przed atakami brute force

Po 5 kolejnych nieprawidłowych kodach weryfikacja 2FA konta jest blokowana na 15 minut. Ekran weryfikacji pokazuje pozostały czas. Licznik zeruje się po każdej udanej weryfikacji.

Reset przez Super Admina

Jeśli pracownik stracił zarówno telefon, jak i kody odzyskiwania:

1. Super Admin otwiera stronę konfiguracji modułu.
2. W tabeli Status 2FA pracowników klika Resetuj w wierszu danego pracownika.
3. 2FA pracownika zostaje usunięte: może zalogować się samym hasłem i będzie musiał ponownie przeprowadzić parowanie (natychmiast, jeśli aktywny jest tryb obowiązkowy).

Wyłączenie własnego 2FA

W sekcji Zarządzaj moim 2FA (menu użytkownika lub panel modułu) kliknij Wyłącz 2FA i potwierdź ważnym kodem TOTP. Wpisanie kodu jest wymagane, aby uniemożliwić wyłączenie przez pozostawioną otwartą sesję.

Aktualizacja z wersji 1.0.x

Aktualizacja do 1.1.0 jest automatyczna i przezroczysta:

• Struktura tabeli jest migrowana (kolumny blokady, poszerzone pole sekretu).
• Istniejące sekrety TOTP pozostają ważne i są automatycznie szyfrowane AES-256 przy najbliższym zapisie. Ponowne parowanie nie jest potrzebne.
• Istniejące kody odzyskiwania pozostają użyteczne: są konwertowane na hash SHA-256 przy pierwszym użyciu.

Rozwiązywanie problemów

„Nieprawidłowy kod”, mimo że kod wygląda poprawnie

W 95% przypadków to różnica zegara. Sprawdź, czy zegar serwera jest zsynchronizowany przez NTP (timedatectl w Linuksie) i czy czas telefonu jest ustawiony automatycznie. Tolerancja modułu wynosi ±30 sekund.

Konto zablokowane po nieudanych próbach

Poczekaj do końca 15-minutowej blokady lub poproś Super Admina o reset 2FA konta ze strony konfiguracji.

Wszystkie dostępy Super Admin są zablokowane

W ostateczności wyłącz moduł w bazie danych: w tabeli ps_module ustaw kolumnę active na 0 dla wiersza df2fa albo tymczasowo zmień nazwę katalogu modules/df2fa. Zaloguj się ponownie, następnie reaktywuj moduł i przeprowadź potrzebne parowania.

Baner przypominający się nie wyświetla

Baner pojawia się tylko u pracowników bez aktywnego 2FA. W trybie opt-in można go ukryć dla bieżącej sesji krzyżykiem zamknięcia; pojawi się ponownie w następnej sesji.

Historia wersji

1.1.0 — 2 lipca 2026

• Kompatybilność z PrestaShop 9 (kontrolery, nowa strona logowania Symfony, Symfony 6.4)
• Szyfrowanie AES-256 sekretu TOTP w bazie, z automatyczną migracją
• Kody odzyskiwania hashowane SHA-256 (10 znaków)
• Blokada 15 minut po 5 nieprawidłowych kodach
• Kod QR generowany w 100% lokalnie (usunięta zależność od CDN)

1.0.0 — 12 marca 2025

• Pierwsza stabilna wersja: TOTP RFC 6238, tryb obowiązkowy lub opt-in, 8 kodów odzyskiwania, reset przez Super Admina, multistore