2FA Google Authenticator para PrestaShop — Documentación

Esta guía cubre la instalación, configuración y uso diario del módulo 2FA Google Authenticator para PrestaShop 8 y 9. El módulo añade una verificación por código de 6 dígitos (estándar TOTP, RFC 6238) después de introducir la contraseña en el back office.

Requisitos

• PrestaShop 8.0 a 8.2 o PrestaShop 9.x
• PHP 7.4 mínimo (PHP 8.1+ requerido por PrestaShop 9)
• Una app TOTP en el teléfono de cada empleado: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, FreeOTP o cualquier app compatible con RFC 6238
• Reloj del servidor sincronizado vía NTP (el caso en todos los hostings modernos)

Instalación

1. En el back office, abre Módulos → Gestor de módulos.
2. Haz clic en Subir un módulo y selecciona el archivo df2fa.zip descargado desde tu cuenta DataFirefly.
3. Haz clic en Instalar. El módulo crea su tabla en la base de datos y registra sus controladores automáticamente.

Configuración del módulo

Abre Módulos → Gestor de módulos → 2FA Google Authenticator → Configurar. La página muestra tres bloques:

Mi cuenta 2FA

Un panel de estado en la parte superior indica si tu propio 2FA está activo, con un botón directo al emparejamiento o a la gestión.

Configuración 2FA

• 2FA obligatorio — en modo forzado, cualquier empleado sin 2FA configurado es redirigido automáticamente a la página de emparejamiento al iniciar sesión. En modo opt-in (por defecto), se muestra un banner recordatorio en el back office y cada empleado activa su 2FA cuando quiera.
• Nombre del emisor (Issuer) — el nombre mostrado en la app TOTP de tus empleados (por defecto, el nombre de la tienda).

Estado 2FA de los empleados

Una tabla lista todos los empleados con su estado 2FA (activo/inactivo), la fecha de configuración y un botón Restablecer para cada empleado con 2FA activo.

Emparejamiento del lado del empleado

1. El empleado abre la página de emparejamiento: mediante el enlace Configurar mi 2FA del menú de usuario (arriba a la derecha del back office), mediante el banner recordatorio, o automáticamente al iniciar sesión si el modo obligatorio está activo.
2. Escanea el código QR mostrado con su app TOTP. El código QR se genera localmente en el navegador — no se envía ningún dato a servicios externos. Si no puede escanear, el secreto puede introducirse manualmente en la app (botón Copiar).
3. Introduce el código de 6 dígitos mostrado por la app para confirmar el emparejamiento.
4. Entonces se muestran los 8 códigos de recuperación de un solo uso — es la única vez que son visibles. El empleado los copia o imprime y los guarda en un lugar seguro.

Iniciar sesión con 2FA

Tras introducir la contraseña, el empleado es redirigido a la pantalla de verificación 2FA e introduce el código de 6 dígitos actual de su app. La verificación permanece válida durante 12 horas para la sesión: no es necesario reintroducir un código en cada página.

Se aplica una tolerancia de deriva de ±30 segundos para absorber pequeñas diferencias de reloj entre el servidor y el teléfono.

Códigos de recuperación

Si el empleado ya no tiene acceso a su app TOTP (teléfono perdido, robado, restablecido):

1. En la pantalla de verificación, haz clic en Usar un código de recuperación.
2. Introduce uno de los 8 códigos de recuperación (10 caracteres).
3. Cada código funciona solo una vez. Una vez conectado, desactiva y reactiva el 2FA para generar un nuevo emparejamiento y una nueva serie de códigos.

Protección anti fuerza bruta

Tras 5 códigos inválidos consecutivos, la verificación 2FA de la cuenta se bloquea durante 15 minutos. La pantalla de verificación muestra el tiempo restante. El contador se reinicia con cada verificación exitosa.

Restablecimiento por un Super Admin

Si un empleado ha perdido tanto su teléfono como sus códigos de recuperación:

1. Un Super Admin abre la página de configuración del módulo.
2. En la tabla Estado 2FA de los empleados, hace clic en Restablecer en la fila del empleado en cuestión.
3. El 2FA del empleado se elimina: puede iniciar sesión solo con su contraseña y deberá volver a emparejar (inmediatamente si el modo obligatorio está activo).

Desactivar tu propio 2FA

Desde Gestionar mi 2FA (menú de usuario o panel del módulo), haz clic en Desactivar el 2FA y confirma con un código TOTP válido. Se exige un código para impedir una desactivación desde una sesión abierta sin vigilancia.

Actualización desde la versión 1.0.x

La actualización a la 1.1.0 es automática y transparente:

• La estructura de la tabla se migra (columnas de bloqueo, campo de secreto ampliado).
• Los secretos TOTP existentes siguen siendo válidos y se cifran con AES-256 automáticamente en su siguiente guardado. No es necesario volver a emparejar.
• Los códigos de recuperación existentes siguen siendo utilizables: se convierten en hashes SHA-256 en su primer uso.

Resolución de problemas

«Código inválido» aunque el código parece correcto

En el 95% de los casos se trata de un desfase de reloj. Verifica que el reloj del servidor está sincronizado por NTP (timedatectl en Linux) y que la hora del teléfono está en modo automático. La tolerancia del módulo es de ±30 segundos.

Cuenta bloqueada tras intentos fallidos

Espera al final del bloqueo de 15 minutos, o pide a un Super Admin que restablezca el 2FA de la cuenta desde la página de configuración.

Todos los accesos Super Admin están bloqueados

Como último recurso, desactiva el módulo en la base de datos: en la tabla ps_module, pon la columna active a 0 para la fila df2fa, o renombra temporalmente la carpeta modules/df2fa. Vuelve a conectarte, reactiva el módulo y rehaz los emparejamientos necesarios.

El banner recordatorio no se muestra

El banner solo aparece para los empleados sin 2FA activo. En modo opt-in puede ocultarse para la sesión actual mediante su botón de cierre; reaparece en la siguiente sesión.

Notas de versión

1.1.0 — 2 de julio de 2026

• Compatibilidad con PrestaShop 9 (controladores, nueva página de inicio de sesión Symfony, Symfony 6.4)
• Cifrado AES-256 del secreto TOTP en la base de datos, con migración automática
• Códigos de recuperación hasheados en SHA-256 (10 caracteres)
• Bloqueo de 15 minutos tras 5 códigos inválidos
• Código QR generado 100% localmente (dependencia de CDN eliminada)

1.0.0 — 12 de marzo de 2025

• Primera versión estable: TOTP RFC 6238, modo obligatorio u opt-in, 8 códigos de recuperación, restablecimiento por Super Admin, multitienda