2FA Google Authenticator dla PrestaShop — Dokumentacja
Instalacja i konfiguracja 2FA panelu administracyjnego i kont klientów w PrestaShop 8 i 9: aplikacja, klucze bezpieczeństwa, kody odzyskiwania, zasady dla profili.
Ten przewodnik opisuje instalację, konfigurację i korzystanie z modułu DataFirefly 2FA dla PrestaShop 8 i 9. Po podaniu hasła moduł wymaga drugiego potwierdzenia tożsamości: 6-cyfrowego kodu z aplikacji uwierzytelniającej (TOTP, RFC 6238), klucza bezpieczeństwa lub passkey (WebAuthn) albo kodu odzyskiwania. Chroni panel administracyjny oraz, opcjonalnie, konta klientów.
Nowości w wersji 2.0.0: całkowicie przebudowana kontrola dostępu (wszystkie strony panelu administracyjnego, w tym strony legacy PrestaShop 8, wywołania AJAX i menedżer plików), klucze bezpieczeństwa i passkeys, ochrona przed ponownym użyciem kodów, zaufane urządzenia, zasady dla poszczególnych profili, pulpit, dziennik bezpieczeństwa, alerty e-mail, 2FA dla klientów za pomocą aplikacji lub e-maila, awaryjne polecenie w wierszu poleceń. Aplikacje skonfigurowane wcześniej działają nadal po aktualizacji.
Wymagania
- PrestaShop od 8.0 do 8.2 lub PrestaShop 9.x (motywy Classic i Hummingbird w części dla klientów)
- PHP 7.2.5 lub nowszy w PrestaShop 8 (PHP 8.1 lub nowszy w PrestaShop 9); testowano do PHP 8.5
- Rozszerzenie PHP OpenSSL (klucze bezpieczeństwa i passkeys)
- Aplikacja uwierzytelniająca w telefonie: Google Authenticator, Microsoft Authenticator, 2FAS, Aegis, 1Password, Bitwarden lub dowolna aplikacja zgodna z TOTP
- HTTPS dla kluczy bezpieczeństwa i passkeys (wymóg przeglądarek)
- Zsynchronizowany zegar serwera (NTP)
Instalacja i aktualizacja
- W panelu administracyjnym otwórz Moduły → Menedżer modułów, kliknij Załaduj moduł i wybierz plik
df2fa-2.0.0.zip. - Moduł tworzy swoje tabele, rejestruje swoje strony i instaluje dwa niewielkie nadpisania (
Employee::isLoggedBackiProfile::getProfileAccess), które rozszerzają ochronę na menedżer plików. - Otwórz Konfiguruj, aby ustawić zasady (patrz niżej).
Instalacja nie wymusza 2FA na nikim: zainstalowanie modułu nie może odciąć Ci dostępu do panelu administracyjnego. Obowiązek 2FA ustawia się następnie osobno dla każdego profilu.
Aktualizacja z wersji 1.x
- Skonfigurowane sekrety zostają zachowane: pracownicy nadal korzystają ze swojej aplikacji. Po aktualizacji wystarczy jednorazowo wpisać kod.
- Sekrety przechowywane jeszcze w postaci jawnej (wersje 1.0.x) są automatycznie szyfrowane.
- Stare kody odzyskiwania pozostają ważne; strona Moje 2FA proponuje utworzenie nowych, lepiej chronionych.
- Dawne ustawienie „2FA wymagane” zostaje zamienione na obowiązek dla wszystkich profili.
Jeśli inne rozszerzenie nadpisuje już Employee::isLoggedBack lub Profile::getProfileAccess, moduł i tak się zainstaluje, ale bez swoich nadpisań; zakładka Przegląd informuje wtedy, że menedżer plików nie jest objęty ochroną.
Logowanie do panelu administracyjnego z 2FA
Po wpisaniu hasła pracownik trafia na ekran pełnoekranowy, bez menu panelu administracyjnego. Wpisuje 6-cyfrowy kod ze swojej aplikacji: można go wkleić, a weryfikacja rozpoczyna się automatycznie po wpisaniu szóstej cyfry. Po zatwierdzeniu kodu pracownik wraca dokładnie na stronę, którą chciał otworzyć.
- Ufaj tej przeglądarce: na komputerze osobistym to pole pozwala nie wpisywać kodu przez wybrany okres (domyślnie 30 dni). Urządzenie można w każdej chwili unieważnić na stronie Moje 2FA.
- Inne sposoby weryfikacji: klucz bezpieczeństwa lub passkey albo kod odzyskiwania.
- Przesunięty zegar telefonu: jeśli kod odpowiada przesuniętej godzinie, ekran to sygnalizuje i wyjaśnia, jak poprawić czas w telefonie (dostęp pozostaje zablokowany).
- Ponowne użycie odrzucone: kodu, który został już użyty, nie można wykorzystać drugi raz.

Zgubiony telefon: kody odzyskiwania i pomoc
Link Użyj kodu odzyskiwania przyjmuje jeden z 10 kodów w formacie XXXXX-XXXXX przekazanych podczas włączania 2FA (małe litery i spacje są akceptowane). Każdy kod działa tylko raz; gdy zostaną 3 kody lub mniej, panel administracyjny proponuje utworzenie nowych. Pomoc Zgubiony telefon? przypomina dostępne rozwiązania:
- Użyć kodu odzyskiwania, a następnie połączyć nowy telefon na stronie Moje 2FA.
- Poprosić administratora SuperAdmin o zresetowanie 2FA w menu Moduły → DataFirefly 2FA → Pracownicy.
- Jedyny administrator bez kodu: w wierszu poleceń na serwerze
php bin/console df2fa:reset email@exemple.com(lub--unlock, aby tylko zdjąć blokadę,--list, aby wyświetlić listę kont).

Włączanie 2FA (pracownik)
Każdy pracownik znajdzie pozycję Uwierzytelnianie dwuskładnikowe w swoim menu (w prawym górnym rogu), ze znacznikiem Włączone lub Wyłączone. Jeśli jego profil wymaga 2FA, kreator otwiera się automatycznie przy następnym logowaniu, w trybie pełnoekranowym, i żadna inna strona nie jest dostępna, dopóki konfiguracja nie zostanie ukończona.

Kreator składa się z trzech kroków:
- Zainstaluj aplikację uwierzytelniającą w telefonie.
- Zeskanuj kod QR, generowany lokalnie w przeglądarce. Alternatywnie wyświetlany jest klucz pogrupowany po 4 znaki z przyciskiem Kopiuj.
- Wprowadź 6-cyfrowy kod, aby potwierdzić.
Zamiast aplikacji pracownik może też wybrać klucz bezpieczeństwa lub passkey.

Następnie jednorazowo wyświetla się 10 kodów odzyskiwania z przyciskami Pobierz, Kopiuj i Drukuj. Aby kontynuować, trzeba zaznaczyć pole „Moje kody odzyskiwania są zapisane w bezpiecznym miejscu”.

Strona Moje 2FA
Zebrano na niej wszystko, co dotyczy konta pracownika:
- Aplikacja uwierzytelniająca: zastąpienie aplikacji (nowy telefon); poprzednia działa, dopóki nowa nie zostanie potwierdzona.
- Klucze bezpieczeństwa i passkeys: dodawanie (z nazwą), lista, usuwanie.
- Kody odzyskiwania: liczba pozostałych kodów, tworzenie nowego zestawu.
- Zaufane urządzenia: przeglądarka, ostatnie użycie, data wygaśnięcia, usuwanie pojedynczo lub wszystkich naraz.
- Ostatnia aktywność: logowania, błędne kody, zmiany.
- Wyłącz 2FA: kodem z aplikacji lub kodem odzyskiwania; niemożliwe, jeśli wymaga tego profil.

Klucze bezpieczeństwa i passkeys
Moduł akceptuje jako drugi składnik klucze FIDO2/WebAuthn (YubiKey, Titan…) oraz wbudowane mechanizmy uwierzytelniania (Windows Hello, Touch ID, passkey w telefonie). To najszybsza metoda, odporna na phishing: klucz odpowiada wyłącznie właściwej witrynie. Moduł weryfikuje wyzwanie, pochodzenie, domenę i licznik podpisów; sklonowany klucz zostaje odrzucony. Klucze bezpieczeństwa wymagają HTTPS (lub localhost).
Pulpit modułu
Otwórz Moduły → DataFirefly 2FA → Konfiguruj. Strona ma pięć zakładek: Przegląd, Pracownicy, Klienci, Ustawienia i Dziennik bezpieczeństwa. Zakładka Przegląd pokazuje wskaźnik wdrożenia, chronionych pracowników i klientów, zablokowane błędne kody i blokady z ostatnich 30 dni, zweryfikowane logowania, wykres z 14 dni, aktywne zabezpieczenia oraz najnowsze zdarzenia. Wszystkie liczby są obliczane na podstawie Twojej bazy danych.

Pracownicy i resetowanie
Zakładka Pracownicy zawiera listę wszystkich aktywnych pracowników z ich profilem, statusem (Chronione, Musi skonfigurować, Niechronione, Zablokowane), metodami, pozostałymi kodami odzyskiwania i ostatnią weryfikacją. SuperAdmin może odblokować konto, usunąć zaufane urządzenia pracownika lub zresetować jego 2FA (zgubiony telefon). Każda akcja jest zapisywana w dzienniku.

Gdy 2FA pracownika zostanie zresetowane lub wyłączone, gdy zostanie użyty kod odzyskiwania, gdy konto zostanie zablokowane lub gdy zostanie dodany klucz, pracownik otrzymuje e-mailem alert bezpieczeństwa w swoim języku.

Ustawienia
- 2FA wymagane dla tych profili: pracownicy zaznaczonych profili skonfigurują 2FA przy następnym logowaniu. Pozostali mogą je włączyć ze swojego menu.
- Ponownie wymagaj kodu: tylko przy każdym logowaniu lub dodatkowo co 4 do 168 godzin (domyślnie co 12 godzin).
- Zaufane przeglądarki: od 7 do 90 dni lub wyłączone.
- Klucze bezpieczeństwa i passkeys: domyślnie włączone.
- Przypomnienie dla pracowników bez 2FA: baner u góry panelu administracyjnego, który pracownik może odłożyć na 7 dni.
- E-maile dotyczące bezpieczeństwa, Nazwa wyświetlana w aplikacji.
- Ochrona przed atakami brute-force: liczba błędnych kodów przed blokadą (domyślnie 5), czas trwania blokady (domyślnie 15 minut), tolerancja zegara (domyślnie ±30 s).
- Konta klientów: patrz następna sekcja.
- Dane: okres przechowywania dziennika (domyślnie 90 dni), zachowanie danych przy odinstalowaniu.
Zalecane wdrożenie: najpierw włącz własne 2FA, następnie zaznacz profil SuperAdmin, a potem pozostałe profile. Zakładka Przegląd pokazuje, ilu pracowników skonfiguruje 2FA przy następnym logowaniu.

2FA dla klientów
Włącz opcję Oferuj 2FA klientom w Ustawieniach. W sekcji Moje konto pojawi się strona Weryfikacja dwuetapowa (motywy Classic i Hummingbird). Wybierasz oferowane metody: aplikację uwierzytelniającą, kod e-mailem lub obie. Możesz też uczynić weryfikację obowiązkową dla wybranych grup klientów, na przykład dla Twojej grupy B2B.

Klient wybiera metodę: aplikację, zalecaną, ponieważ działa nawet offline, lub kod e-mailem, prostszy (6 cyfr, ważny 10 minut, ponowne wysłanie najwyżej raz na minutę).

Włączanie za pomocą aplikacji przebiega w tych samych trzech krokach co u pracowników, po czym klient otrzymuje swoje 10 kodów odzyskiwania.

Przy każdym logowaniu, również w procesie składania zamówienia, przez logowanie społecznościowe lub po zresetowaniu hasła, klient musi wpisać kod, zanim uzyska dostęp do swojego konta, zamówień i adresów. Jeśli chce, może wybrać, aby nie pytać go ponownie na tym urządzeniu przez 30 dni.

Na tej samej stronie klient zarządza swoją metodą, kodami odzyskiwania i zaufanymi urządzeniami oraz może wyłączyć weryfikację, chyba że wymaga jej jego grupa.

W przypadku metody e-mail kod jest wysyłany automatycznie po otwarciu ekranu weryfikacji, z szablonem przetłumaczonym na 8 języków.

W panelu administracyjnym zakładka Klienci zawiera listę chronionych klientów (metoda, data, ostatnia weryfikacja, urządzenia) i pozwala odblokować konto lub wyłączyć 2FA klienta po zweryfikowaniu jego tożsamości.

Dziennik bezpieczeństwa
Dziennik rejestruje zweryfikowane logowania, błędne kody, blokady, włączenia i wyłączenia, resetowania, użycie kodów odzyskiwania, zaufane urządzenia i klucze, wraz z datą, kontem, metodą, adresem IP i urządzeniem. Można go filtrować według pracowników lub klientów, a stare wpisy są automatycznie usuwane po upływie wybranego okresu.

Co chroni moduł
- Wszystkie strony panelu administracyjnego: strony legacy (również w PrestaShop 8), strony Symfony, wywołania AJAX (odpowiedź 401), formularze wysyłane metodą POST, menedżer plików.
- Stan „zweryfikowany” jest przechowywany po stronie serwera i powiązany z sesją PrestaShop pracownika: nowe logowanie zawsze zaczyna się jako niezweryfikowane.
- Sekrety zaszyfrowane w bazie danych, kody odzyskiwania przechowywane jako skróty z użyciem tajnego klucza serwera, porównania w stałym czasie, ochrona przed ponownym użyciem kodów i atakami brute-force, tokeny CSRF przy wszystkich akcjach.
Webservice (klucze API) i API administracyjne PrestaShop 9 (dane uwierzytelniające OAuth) nie korzystają z logowania pracownika, więc nie są objęte 2FA. Chroń te klucze i ograniczaj ich uprawnienia.
Rozwiązywanie problemów
„Ten kod byłby ważny przy przesunięciu o X min”
Czas w telefonie jest przesunięty. Włącz w telefonie automatyczną datę i godzinę, a następnie spróbuj ponownie. Sprawdź też zegar serwera (timedatectl).
„Ten kod został już użyty”
Moduł odrzuca ponowne użycie kodu: poczekaj na następny kod w aplikacji (30 sekund).
Konto zablokowane po zbyt wielu błędnych kodach
Poczekaj na koniec blokady, poproś administratora SuperAdmin o jej zdjęcie w zakładce Pracownicy lub uruchom php bin/console df2fa:reset email@exemple.com --unlock.
Żaden SuperAdmin nie może się zalogować
Na serwerze polecenie php bin/console df2fa:reset email@exemple.com usuwa 2FA ze wskazanego konta; pracownik loguje się ponownie hasłem i konfiguruje 2FA od nowa.
Klucz bezpieczeństwa nie jest proponowany
Witryna musi działać przez HTTPS, opcja musi być włączona w Ustawieniach, a na serwerze musi być dostępne rozszerzenie OpenSSL.
Odinstalowanie
Domyślnie odinstalowanie usuwa tabele, ustawienia, nadpisania i strony modułu. Jeśli włączona jest opcja Zachowaj dane przy odinstalowaniu, zaszyfrowane sekrety, klucze i dziennik zostają zachowane na potrzeby ponownej instalacji.
Informacje o wersjach
2.0.0 (31 października 2026)
- Bezpieczeństwo: przebudowana kontrola dostępu. Objęcie ochroną stron legacy PrestaShop 8, naprawione obejścia przez
&logouti nagłówek AJAX, ścisła biała lista, stan weryfikacji powiązany z sesją po stronie serwera, objęcie ochroną menedżera plików. - Ochrona przed ponownym użyciem kodów, wykrywanie przesunięcia zegara, wzmocnione kody odzyskiwania (10 kodów, skróty z kluczem serwera), resetowanie zarezerwowane dla SuperAdminów z tokenem CSRF.
- Nowość: klucze bezpieczeństwa i passkeys (WebAuthn), zaufane urządzenia, zasady dla poszczególnych profili, pulpit, dziennik bezpieczeństwa, alerty e-mail, polecenie
df2fa:reset. - Nowość: 2FA dla klientów za pomocą aplikacji lub kodu e-mail, opcjonalnie obowiązkowe dla wybranych grup.
- Przebudowany interfejs: pełnoekranowy ekran weryfikacji i kreator konfiguracji, strona Moje 2FA, pozycja w menu pracownika dla wszystkich profili.
- Pełne tłumaczenia na 8 języków (panel administracyjny, sklep, e-maile). Testowano na PrestaShop 8.2.1 i 9.1.5, PHP od 7.4 do 8.5.
1.1.1 (8 września 2026)
- Poprawka tabeli Status 2FA pracowników, interfejs przetłumaczony na 7 języków.
1.1.0 (2 lipca 2026)
- Zgodność z PrestaShop 9, szyfrowanie sekretu, haszowane kody odzyskiwania, blokada po 5 błędnych kodach, lokalnie generowany kod QR.
1.0.0 (12 marca 2025)
- Pierwsza wersja: TOTP, tryb obowiązkowy lub opcjonalny, kody odzyskiwania, resetowanie przez SuperAdmina.