2FA Google Authenticator para PrestaShop: documentação
Instalar e configurar a dupla autenticação TOTP no back-office do PrestaShop 8 e 9: emparelhamento, códigos de recuperação, modo obrigatório e proteção antiforça bruta.
Este guia cobre a instalação, a configuração e a utilização diária do módulo 2FA Google Authenticator para PrestaShop 8 e 9. O módulo acrescenta uma verificação por código de 6 dígitos (norma TOTP, RFC 6238) depois da introdução da palavra-passe no back-office.
Pré-requisitos
- PrestaShop 8.0 a 8.2 ou PrestaShop 9.x
- PHP 7.4 no mínimo (PHP 8.1+ exigido pelo PrestaShop 9)
- Uma aplicação TOTP no telemóvel de cada colaborador: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, FreeOTP ou qualquer aplicação compatível com a RFC 6238
- Relógio do servidor sincronizado por NTP (o que acontece em todos os alojamentos modernos)
Instalação
- No back-office, abra Módulos → Gestor de módulos.
- Clique em Instalar um módulo e selecione o ficheiro
df2fa.zipdescarregado a partir da sua conta DataFirefly. - Clique em Instalar. O módulo cria a sua tabela na base de dados e regista os seus controladores automaticamente.
A instalação não ativa a 2FA para ninguém: cada colaborador tem de fazer o seu emparelhamento (ou ser obrigado a fazê-lo através do modo obrigatório, ver abaixo). Não corre o risco de ficar bloqueado fora do back-office ao instalar o módulo.
Configuração do módulo
Abra Módulos → Gestor de módulos → 2FA Google Authenticator → Configurar. A página apresenta três blocos:
A minha conta 2FA
Um painel de estado no topo da página indica se a sua própria 2FA está ativa, com um botão direto para o emparelhamento ou para a gestão.
Configuração 2FA
- 2FA obrigatória — no modo forçado, qualquer colaborador sem 2FA configurada é automaticamente reencaminhado para a página de emparelhamento assim que inicia sessão. No modo opt-in (predefinido), é apresentada uma faixa de lembrete no back-office e cada colaborador ativa a sua 2FA quando quiser.
- Nome do emissor (Issuer) — o nome apresentado na aplicação TOTP dos seus colaboradores (por predefinição, o nome da loja).
Estado 2FA dos colaboradores
Uma tabela lista todos os colaboradores com o respetivo estado 2FA (ativo/inativo), a data de configuração e um botão Repor para cada colaborador com a 2FA ativa.
Implementação progressiva recomendada: comece no modo opt-in, deixe a faixa de lembrete fazer o seu trabalho durante alguns dias, verifique a adesão na tabela e só depois passe para o modo obrigatório.
Emparelhamento do lado do colaborador
- O colaborador abre a página de emparelhamento: pela ligação Configurar a minha 2FA do menu de utilizador (canto superior direito do back-office), pela faixa de lembrete, ou automaticamente ao iniciar sessão se o modo obrigatório estiver ativo.
- Lê o código QR apresentado com a sua aplicação TOTP. O código QR é gerado localmente no navegador: nenhum dado é enviado para um serviço externo. Se não for possível ler o código, o segredo pode ser introduzido manualmente na aplicação (botão Copiar).
- Introduz o código de 6 dígitos apresentado pela aplicação para validar o emparelhamento.
- Os 8 códigos de recuperação de utilização única são então apresentados: é a única vez em que ficam visíveis. O colaborador copia-os ou imprime-os e guarda-os em local seguro.
Os códigos de recuperação são guardados com hash (SHA-256): não podem ser mostrados de novo mais tarde. Se forem perdidos, será necessário desativar e voltar a ativar a 2FA, ou passar por uma reposição feita por um Super Admin.
Início de sessão com 2FA
Depois de introduzir a palavra-passe, o colaborador é reencaminhado para o ecrã de verificação 2FA e introduz o código de 6 dígitos atual da sua aplicação. A verificação continua válida durante 12 horas para a sessão: não é preciso introduzir um código em cada página.
É aplicada uma tolerância de desvio de ±30 segundos para absorver as pequenas diferenças de relógio entre o servidor e o telemóvel.
Códigos de recuperação
Se o colaborador deixar de ter acesso à sua aplicação TOTP (telemóvel perdido, roubado ou reposto):
- No ecrã de verificação, clique em Utilizar um código de recuperação.
- Introduza um dos 8 códigos de recuperação (10 caracteres).
- Cada código funciona uma única vez. Depois de iniciar sessão, desative e volte a ativar a 2FA para gerar um novo emparelhamento e uma nova série de códigos.
Proteção antiforça bruta
Após 5 códigos inválidos consecutivos, a verificação 2FA da conta fica bloqueada durante 15 minutos. O ecrã de verificação mostra o tempo restante. O contador é reposto a zero em cada verificação bem-sucedida.
Reposição por um Super Admin
Se um colaborador perdeu ao mesmo tempo o telemóvel e os códigos de recuperação:
- Um Super Admin abre a página de configuração do módulo.
- Na tabela Estado 2FA dos colaboradores, clica em Repor na linha do colaborador em causa.
- A 2FA do colaborador é eliminada: pode iniciar sessão apenas com a palavra-passe e terá de refazer o emparelhamento (de imediato se o modo obrigatório estiver ativo).
Desativar a sua própria 2FA
A partir de Gerir a minha 2FA (menu de utilizador ou painel do módulo), clique em Desativar a 2FA e confirme com um código TOTP válido. A introdução de um código é exigida para impedir uma desativação a partir de uma sessão deixada aberta.
Atualização a partir da versão 1.0.x
A atualização para a 1.1.0 é automática e transparente:
- A estrutura da tabela é migrada (colunas de bloqueio, campo do segredo alargado).
- Os segredos TOTP existentes continuam válidos e são cifrados em AES-256 automaticamente na gravação seguinte. Não é necessário voltar a emparelhar.
- Os códigos de recuperação existentes continuam utilizáveis: são convertidos em hash SHA-256 na primeira utilização.
Migração PS8 → PS9: o módulo é idêntico nas duas versões. Pode migrar a sua loja sem atualizar o módulo nem voltar a emparelhar os colaboradores.
Resolução de problemas
«Código inválido» apesar de o código parecer correto
Em 95 % dos casos trata-se de um desvio de relógio. Verifique se o relógio do servidor está sincronizado por NTP (timedatectl em Linux) e se a hora do telemóvel está em modo automático. A tolerância do módulo é de ±30 segundos.
Conta bloqueada após tentativas falhadas
Aguarde o fim do bloqueio de 15 minutos, ou peça a um Super Admin que reponha a 2FA da conta a partir da página de configuração.
Todos os acessos de Super Admin estão bloqueados
Em último recurso, desative o módulo na base de dados: na tabela ps_module, passe a coluna active para 0 na linha df2fa, ou mude temporariamente o nome da pasta modules/df2fa. Volte a iniciar sessão, reative o módulo e refaça os emparelhamentos necessários.
A faixa de lembrete não aparece
A faixa só aparece aos colaboradores sem 2FA ativa. No modo opt-in, pode ser fechada para a sessão em curso através da cruz de fecho; reaparece na sessão seguinte.
Notas de versão
1.1.0 — 2 de julho de 2026
- Compatibilidade com o PrestaShop 9 (controladores, nova página de início de sessão Symfony, Symfony 6.4)
- Cifra AES-256 do segredo TOTP na base de dados, com migração automática
- Códigos de recuperação com hash SHA-256 (10 caracteres)
- Bloqueio de 15 minutos após 5 códigos inválidos
- Código QR gerado 100 % localmente (dependência de CDN eliminada)
1.0.0 — 12 de março de 2025
- Primeira versão estável: TOTP RFC 6238, modo obrigatório ou opt-in, 8 códigos de recuperação, reposição por Super Admin, multiloja