2FA Google Authenticator for PrestaShop — Documentation

This guide covers installing, configuring and using the 2FA Google Authenticator module for PrestaShop 8 and 9 day to day. The module adds a 6-digit code verification (TOTP standard, RFC 6238) after the password is entered on the back office.

Requirements

• PrestaShop 8.0 to 8.2 or PrestaShop 9.x
• PHP 7.4 minimum (PHP 8.1+ required by PrestaShop 9)
• A TOTP app on each employee’s phone: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, FreeOTP or any RFC 6238 compatible app
• Server clock synchronized via NTP (the case on all modern hosting)

Installation

1. In the back office, open Modules → Module Manager.
2. Click Upload a module and select the df2fa.zip file downloaded from your DataFirefly account.
3. Click Install. The module creates its database table and registers its controllers automatically.

Module configuration

Open Modules → Module Manager → 2FA Google Authenticator → Configure. The page shows three blocks:

My 2FA account

A status panel at the top shows whether your own 2FA is active, with a direct button to pairing or management.

2FA configuration

• Mandatory 2FA — in forced mode, any employee without configured 2FA is automatically redirected to the pairing page at login. In opt-in mode (default), a reminder banner is shown in the back office and each employee enables their 2FA whenever they choose.
• Issuer name — the name shown in your employees’ TOTP app (defaults to the shop name).

Employee 2FA status

A table lists all employees with their 2FA status (active/inactive), setup date, and a Reset button for each employee with active 2FA.

Pairing on the employee side

1. The employee opens the pairing page: via the Set up my 2FA link in the user menu (top right of the back office), via the reminder banner, or automatically at login if mandatory mode is enabled.
2. They scan the displayed QR code with their TOTP app. The QR code is generated locally in the browser — no data is sent to any external service. If scanning is not possible, the secret can be entered manually in the app (Copy button).
3. They enter the 6-digit code shown by the app to confirm the pairing.
4. The 8 single-use recovery codes are then displayed — this is the only time they are visible. The employee copies or prints them and keeps them somewhere safe.

Logging in with 2FA

After entering the password, the employee is redirected to the 2FA verification screen and enters the current 6-digit code from their app. The verification stays valid for 12 hours for the session: there is no need to re-enter a code on every page.

A ±30 second drift tolerance is applied to absorb small clock differences between the server and the phone.

Recovery codes

If the employee no longer has access to their TOTP app (phone lost, stolen, reset):

1. On the verification screen, click Use a recovery code.
2. Enter one of the 8 recovery codes (10 characters).
3. Each code works only once. Once logged in, disable then re-enable 2FA to generate a new pairing and a fresh set of codes.

Brute-force protection

After 5 consecutive invalid codes, 2FA verification for the account is locked for 15 minutes. The verification screen shows the remaining time. The counter resets on every successful verification.

Super Admin reset

If an employee has lost both their phone and their recovery codes:

1. A Super Admin opens the module configuration page.
2. In the Employee 2FA status table, they click Reset on the relevant employee’s row.
3. The employee’s 2FA is removed: they can log in with their password alone and will need to pair again (immediately if mandatory mode is enabled).

Disabling your own 2FA

From Manage my 2FA (user menu or module panel), click Disable 2FA and confirm with a valid TOTP code. A code is required to prevent deactivation from an unattended open session.

Upgrading from version 1.0.x

Upgrading to 1.1.0 is automatic and transparent:

• The table structure is migrated (lockout columns, widened secret field).
• Existing TOTP secrets stay valid and are encrypted with AES-256 automatically on their next save. No re-pairing needed.
• Existing recovery codes remain usable: they are converted to SHA-256 hashes on first use.

Troubleshooting

“Invalid code” although the code looks correct

In 95% of cases this is a clock offset. Check that the server clock is synchronized via NTP (timedatectl on Linux) and that the phone’s time is set to automatic. The module’s tolerance is ±30 seconds.

Account locked after failed attempts

Wait for the 15-minute lockout to end, or ask a Super Admin to reset the account’s 2FA from the configuration page.

All Super Admin access is blocked

As a last resort, disable the module in the database: in the ps_module table, set the active column to 0 for the df2fa row, or temporarily rename the modules/df2fa folder. Log back in, then re-enable the module and redo the necessary pairings.

The reminder banner does not show

The banner only appears for employees without active 2FA. In opt-in mode it can be dismissed for the current session via its close button; it reappears on the next session.

Release notes

1.1.0 — July 2, 2026

• PrestaShop 9 compatibility (controllers, new Symfony login page, Symfony 6.4)
• AES-256 encryption of the TOTP secret in the database, with automatic migration
• Recovery codes hashed with SHA-256 (10 characters)
• 15-minute lockout after 5 invalid codes
• QR code generated 100% locally (CDN dependency removed)

1.0.0 — March 12, 2025

• First stable release: TOTP RFC 6238, mandatory or opt-in mode, 8 recovery codes, Super Admin reset, multistore