2FA Google Authenticator per PrestaShop — Documentazione
Installa e configura la 2FA del back office e degli account clienti di PrestaShop 8 e 9: app, chiavi di sicurezza, codici di recupero, regole per profilo.
Questa guida illustra l’installazione, la configurazione e l’uso del modulo DataFirefly 2FA per PrestaShop 8 e 9. Dopo la password, il modulo richiede una seconda prova d’identità: un codice a 6 cifre da un’app di autenticazione (TOTP, RFC 6238), una chiave di sicurezza o una passkey (WebAuthn), oppure un codice di recupero. Protegge il back office e, facoltativamente, gli account dei clienti.
Novità della versione 2.0.0: controllo degli accessi completamente riscritto (tutte le pagine del back office, comprese le pagine legacy di PrestaShop 8, le chiamate AJAX e il gestore file), chiavi di sicurezza e passkey, protezione contro il riutilizzo dei codici, dispositivi attendibili, regole per profilo, dashboard, registro di sicurezza, avvisi via e-mail, 2FA dei clienti tramite app o e-mail, comando di emergenza da riga di comando. Le app già configurate continuano a funzionare dopo l’aggiornamento.
Requisiti
- PrestaShop da 8.0 a 8.2 oppure PrestaShop 9.x (temi Classic e Hummingbird per la parte clienti)
- PHP 7.2.5 o superiore su PrestaShop 8 (PHP 8.1 o superiore su PrestaShop 9); testato fino a PHP 8.5
- Estensione PHP OpenSSL (chiavi di sicurezza e passkey)
- Un’app di autenticazione sul telefono: Google Authenticator, Microsoft Authenticator, 2FAS, Aegis, 1Password, Bitwarden o qualsiasi app compatibile TOTP
- HTTPS per le chiavi di sicurezza e le passkey (requisito dei browser)
- Orologio del server sincronizzato (NTP)
Installazione e aggiornamento
- Nel back office, apri Moduli → Gestione moduli, fai clic su Carica un modulo e seleziona
df2fa-2.0.0.zip. - Il modulo crea le sue tabelle, registra le sue pagine e installa due piccoli override (
Employee::isLoggedBackeProfile::getProfileAccess) che estendono la protezione al gestore file. - Apri Configura per impostare le regole (vedi più avanti).
L’installazione non impone la 2FA a nessuno: installando il modulo non puoi restare bloccato fuori dal back office. L’obbligo si imposta poi profilo per profilo.
Aggiornamento dalla 1.x
- I segreti già configurati vengono conservati: i tuoi dipendenti mantengono la loro app. Devono solo inserire il codice una volta dopo l’aggiornamento.
- I segreti ancora memorizzati in chiaro (versioni 1.0.x) vengono cifrati automaticamente.
- I vecchi codici di recupero restano validi; la pagina La mia 2FA propone di crearne di nuovi, protetti meglio.
- La vecchia impostazione « 2FA obbligatoria » viene convertita in un obbligo per tutti i profili.
Se un’altra estensione esegue già l’override di Employee::isLoggedBack o Profile::getProfileAccess, il modulo si installa comunque senza i suoi override; la Panoramica indica allora che il gestore file non è coperto.
Accesso al back office con la 2FA
Dopo la password, il dipendente arriva su una schermata a tutto schermo, senza il menu del back office. Inserisce il codice a 6 cifre della sua app: il codice si può incollare e la verifica parte da sola alla sesta cifra. Una volta convalidato il codice, torna esattamente alla pagina che aveva richiesto.
- Rendi attendibile questo browser: su un computer personale, questa casella evita di richiedere il codice per la durata scelta (30 giorni per impostazione predefinita). Il dispositivo resta revocabile dalla pagina La mia 2FA.
- Altri modi di verifica: chiave di sicurezza o passkey, oppure codice di recupero.
- Orologio del telefono sfasato: se il codice corrisponde a un orario sfasato, la schermata lo segnala e spiega come correggere l’ora del telefono (l’accesso resta negato).
- Riutilizzo rifiutato: un codice già usato non può servire una seconda volta.

Telefono perso: codici di recupero e aiuto
Il link Usa un codice di recupero accetta uno dei 10 codici nel formato XXXXX-XXXXX forniti al momento dell’attivazione (minuscole e spazi accettati). Ogni codice funziona una sola volta; quando ne restano 3, il back office invita a crearne di nuovi. L’aiuto Hai perso il telefono? ricorda le soluzioni possibili:
- Usare un codice di recupero, poi collegare il nuovo telefono dalla pagina La mia 2FA.
- Chiedere a un SuperAdmin di reimpostare la 2FA in Moduli → DataFirefly 2FA → Dipendenti.
- Unico amministratore senza codice: da riga di comando sul server,
php bin/console df2fa:reset email@exemple.com(oppure--unlockper rimuovere solo un blocco,--listper elencare gli account).

Attivare la propria 2FA (dipendente)
Ogni dipendente trova la voce Autenticazione a due fattori nel proprio menu (in alto a destra), con un’etichetta Attiva o Disattivata. Se il suo profilo richiede la 2FA, la procedura guidata si apre automaticamente al prossimo accesso, a tutto schermo, e nessun’altra pagina è accessibile finché non è completata.

La procedura guidata si svolge in tre passaggi:
- Installa un’app di autenticazione sul telefono.
- Scansiona il codice QR, generato localmente nel browser. In alternativa, la chiave viene mostrata in gruppi di 4 caratteri con un pulsante Copia.
- Inserisci il codice a 6 cifre per confermare.
Il dipendente può anche scegliere una chiave di sicurezza o una passkey al posto dell’app.

I 10 codici di recupero vengono poi mostrati una sola volta, con i pulsanti Scarica, Copia e Stampa. Per continuare bisogna spuntare « Ho salvato i miei codici di recupero in un luogo sicuro ».

La pagina La mia 2FA
Riunisce tutto ciò che riguarda l’account del dipendente:
- App di autenticazione: sostituisci l’app (nuovo telefono); quella precedente funziona finché la nuova non viene confermata.
- Chiavi di sicurezza e passkey: aggiungi (con un nome), elenca, rimuovi.
- Codici di recupero: numero rimasto, creazione di una nuova serie.
- Dispositivi attendibili: browser, ultimo utilizzo, scadenza, rimozione uno per uno o tutti insieme.
- Attività recente: accessi, codici errati, modifiche.
- Disattiva la 2FA: con un codice dell’app o un codice di recupero, non possibile se il profilo la richiede.

Chiavi di sicurezza e passkey
Il modulo accetta come secondo fattore le chiavi FIDO2/WebAuthn (YubiKey, Titan…) e gli autenticatori integrati (Windows Hello, Touch ID, passkey del telefono). È il metodo più rapido e resiste al phishing: la chiave risponde solo al sito giusto. Il modulo verifica la sfida, l’origine, il dominio e il contatore delle firme; una chiave clonata viene rifiutata. Le chiavi di sicurezza richiedono HTTPS (o localhost).
Dashboard del modulo
Apri Moduli → DataFirefly 2FA → Configura. La pagina contiene cinque schede: Panoramica, Dipendenti, Clienti, Impostazioni e Registro di sicurezza. La Panoramica mostra il tasso di adozione, i dipendenti e i clienti protetti, i codici errati bloccati e i blocchi negli ultimi 30 giorni, gli accessi verificati, un grafico sugli ultimi 14 giorni, le protezioni attive e gli ultimi eventi. Tutti i dati sono calcolati a partire dal tuo database.

Dipendenti e reimpostazione
La scheda Dipendenti elenca ogni dipendente attivo con il suo profilo, il suo stato (Protetto, Da configurare, Non protetto, Bloccato), i suoi metodi, i codici di recupero rimasti e l’ultima verifica. Un SuperAdmin può sbloccare un account, revocarne i dispositivi attendibili o reimpostarne la 2FA (telefono perso). Ogni azione viene registrata.

Quando la sua 2FA viene reimpostata o disattivata, quando viene usato un codice di recupero, quando il suo account viene bloccato o quando viene aggiunta una chiave, il dipendente riceve un avviso di sicurezza via e-mail, nella sua lingua.

Impostazioni
- 2FA obbligatoria per questi profili: i dipendenti dei profili selezionati configurano la 2FA al prossimo accesso. Gli altri possono attivarla dal proprio menu.
- Richiedi di nuovo il codice: solo a ogni accesso, oppure anche ogni 4-168 ore (12 ore per impostazione predefinita).
- Browser attendibili: da 7 a 90 giorni, oppure disattivati.
- Chiavi di sicurezza e passkey: attive per impostazione predefinita.
- Promemoria per i dipendenti senza 2FA: banner in cima al back office, che il dipendente può rimandare di 7 giorni.
- E-mail di sicurezza, Nome mostrato nell’app.
- Protezione dagli attacchi brute force: numero di codici errati prima del blocco (5 per impostazione predefinita), durata del blocco (15 minuti per impostazione predefinita), tolleranza dell’orologio (±30 s per impostazione predefinita).
- Account dei clienti: vedi la sezione successiva.
- Dati: durata di conservazione del registro (90 giorni per impostazione predefinita), conservazione dei dati alla disinstallazione.
Distribuzione consigliata: attiva prima la tua 2FA, poi seleziona il profilo SuperAdmin, quindi gli altri profili. La scheda Panoramica indica quanti dipendenti configureranno la 2FA al prossimo accesso.

2FA dei clienti
Attiva Proponi la 2FA ai clienti in Impostazioni. Nella sezione Il mio account compare una pagina Verifica in due passaggi (temi Classic e Hummingbird). Scegli tu i metodi proposti: app di autenticazione, codice via e-mail o entrambi. Puoi anche rendere la verifica obbligatoria per alcuni gruppi di clienti, ad esempio il tuo gruppo B2B.

Il cliente sceglie il suo metodo: l’app, consigliata perché funziona anche offline, oppure il codice via e-mail, più semplice (6 cifre, valido 10 minuti, nuovo invio limitato a uno al minuto).

L’attivazione tramite app segue gli stessi tre passaggi previsti per i dipendenti, poi il cliente riceve i suoi 10 codici di recupero.

A ogni accesso, anche dal processo di checkout, da un accesso tramite social network o dopo una reimpostazione della password, il cliente deve inserire il suo codice prima di accedere al suo account, ai suoi ordini o ai suoi indirizzi. Se lo desidera, può chiedere di non ricevere più la richiesta su quel dispositivo per 30 giorni.

Dalla stessa pagina, il cliente gestisce il suo metodo, i suoi codici di recupero e i suoi dispositivi attendibili, e può disattivare la verifica, salvo se il suo gruppo la impone.

Con il metodo e-mail, il codice viene inviato automaticamente all’apertura della schermata di verifica, con un modello tradotto in 8 lingue.

Nel back office, la scheda Clienti elenca i clienti protetti (metodo, data, ultima verifica, dispositivi) e permette di sbloccare un account o di disattivarne la 2FA dopo averne verificato l’identità.

Registro di sicurezza
Il registro memorizza gli accessi verificati, i codici errati, i blocchi, le attivazioni e disattivazioni, le reimpostazioni, l’uso dei codici di recupero, i dispositivi attendibili e le chiavi, con data, account, metodo, indirizzo IP e dispositivo. Si può filtrare per dipendenti o per clienti e viene ripulito automaticamente in base alla durata scelta.

Cosa protegge il modulo
- Tutte le pagine del back office: pagine legacy (anche su PrestaShop 8), pagine Symfony, chiamate AJAX (risposta 401), moduli inviati in POST, gestore file.
- Lo stato « verificato » è conservato lato server e legato alla sessione PrestaShop del dipendente: un nuovo accesso riparte sempre come non verificato.
- Segreti cifrati nel database, codici di recupero memorizzati come hash con una chiave segreta del server, confronti a tempo costante, protezione contro il riutilizzo dei codici e gli attacchi brute force, token CSRF su tutte le azioni.
Il webservice (chiavi API) e l’API di amministrazione di PrestaShop 9 (credenziali OAuth) non passano da un accesso dipendente: non rientrano nella 2FA. Proteggi queste chiavi e limitane i permessi.
Risoluzione dei problemi
« Questo codice sarebbe valido con uno scarto di X min »
L’ora del telefono è sfasata. Attiva data e ora automatiche sul telefono, poi riprova. Controlla anche l’orologio del server (timedatectl).
« Questo codice è già stato usato »
Il modulo rifiuta il riutilizzo: attendi il codice successivo nell’app (30 secondi).
Account bloccato dopo troppi codici errati
Attendi la fine del blocco, fallo rimuovere da un SuperAdmin dalla scheda Dipendenti oppure esegui php bin/console df2fa:reset email@exemple.com --unlock.
Nessun SuperAdmin riesce più ad accedere
Dal server, php bin/console df2fa:reset email@exemple.com rimuove la 2FA dall’account indicato; il dipendente accede di nuovo con la sua password e configura nuovamente la 2FA.
La chiave di sicurezza non viene proposta
Il sito deve essere servito in HTTPS, l’opzione deve essere attiva in Impostazioni e l’estensione OpenSSL deve essere presente sul server.
Disinstallazione
Per impostazione predefinita, la disinstallazione elimina le tabelle, le impostazioni, gli override e le pagine del modulo. Se l’opzione Conserva i dati alla disinstallazione è attiva, i segreti cifrati, le chiavi e il registro vengono conservati per una successiva reinstallazione.
Note di versione
2.0.0 (31 ottobre 2026)
- Sicurezza: controllo degli accessi riscritto. Pagine legacy di PrestaShop 8 coperte, aggiramenti tramite
&logoute tramite intestazione AJAX corretti, whitelist rigorosa, stato verificato legato alla sessione lato server, gestore file coperto. - Protezione contro il riutilizzo dei codici, rilevamento dello sfasamento dell’orologio, codici di recupero rafforzati (10 codici, hash con chiave del server), reimpostazione riservata ai SuperAdmin con token CSRF.
- Novità: chiavi di sicurezza e passkey (WebAuthn), dispositivi attendibili, regole per profilo, dashboard, registro di sicurezza, avvisi via e-mail, comando
df2fa:reset. - Novità: 2FA dei clienti tramite app o codice via e-mail, facoltativamente obbligatoria per gruppo.
- Interfaccia rinnovata: schermata di verifica e procedura guidata di configurazione a tutto schermo, pagina La mia 2FA, voce nel menu del dipendente per tutti i profili.
- Traduzioni complete in 8 lingue (back office, front office, e-mail). Testato su PrestaShop 8.2.1 e 9.1.5, PHP da 7.4 a 8.5.
1.1.1 (8 settembre 2026)
- Correzione della tabella Stato 2FA dei dipendenti, interfaccia tradotta in 7 lingue.
1.1.0 (2 luglio 2026)
- Compatibilità con PrestaShop 9, cifratura del segreto, codici di recupero con hash, blocco dopo 5 codici errati, codice QR locale.
1.0.0 (12 marzo 2025)
- Prima versione: TOTP, modalità obbligatoria o facoltativa, codici di recupero, reimpostazione da parte del SuperAdmin.