Autenticação em dois fatores no admin do Magento 2: setup e correções

Desde o Magento 2.4.0, todo login no admin exige um segundo fator. O módulo Magento_TwoFactorAuth vem habilitado tanto no Magento Open Source quanto no Adobe Commerce, e um usuário do admin não chega ao dashboard até configurar um provider. É um dos recursos de segurança mais úteis da plataforma e também uma das fontes mais comuns de chamados de suporte: celulares perdidos, e-mails que nunca chegam, ambientes locais onde ninguém consegue entrar.

Este artigo cobre como o módulo funciona, como configurá-lo para uma equipe, os comandos de CLI que resolvem a maioria dos problemas e o que fazer em desenvolvimento local sem enfraquecer a produção.

Como funciona o primeiro login

Quando um usuário do admin sem provider configurado faz login com a senha correta, o Magento não abre o dashboard. Ele envia um e-mail para esse usuário com um link para configurar a autenticação em dois fatores. O usuário abre o link, escolhe um provider (ou recebe o que a loja força) e conclui a configuração. Daí em diante, cada login pede a senha e depois o segundo fator.

A etapa do e-mail é intencional. Ela prova que quem está fazendo login também controla a caixa de correio da conta. Também significa que, se a loja não consegue enviar e-mail, novos usuários do admin não conseguem terminar a configuração. É a primeira coisa a checar quando alguém diz que está preso na tela "you need to configure two factor authentication".

Providers disponíveis

O módulo inclui vários providers. Quais você vê depende da sua versão, então confira a tela de configuração ou liste pela CLI:

bin/magento security:tfa:providers

• Google Authenticator. Senhas de uso único baseadas em tempo, o padrão. Apesar do nome, funciona com qualquer app TOTP, como Microsoft Authenticator, 1Password ou Bitwarden. É a escolha mais simples para a maioria das equipes.
• Duo Security. Notificações push pelo Duo. Precisa de uma conta Duo e das chaves de integração do painel admin do Duo, informadas na configuração do Magento.
• Chaves de segurança U2F. Chaves de hardware como a YubiKey, usando WebAuthn no navegador. É a opção mais forte contra phishing. As chaves de segurança exigem HTTPS, e a chave fica atrelada ao domínio do admin em que foi registrada.

Forçando um provider

Por padrão, os usuários podem escolher entre os providers habilitados. Para uma equipe, é mais fácil dar suporte a um só. Defina os providers forçados em Stores, Configuration, Security, 2FA, ou pela CLI:

bin/magento config:set twofactorauth/general/force_providers google

Para permitir mais de um, separe os códigos por vírgula, por exemplo google,u2fkey. Use os códigos impressos pelo security:tfa:providers. Trave o valor no app/etc/env.php com --lock-env se não quiser que seja alterado pelo admin.

Comandos de CLI que resolvem a maioria dos problemas

Um usuário perdeu o celular

Resete o provider desse usuário. No próximo login ele passa pela configuração de novo:

bin/magento security:tfa:reset john.smith google

Os argumentos são o nome de usuário do admin e o código do provider. Um administrador também pode fazer isso no admin, na página de edição do usuário, onde a configuração de dois fatores pode ser resetada por provider.

Antes de resetar, confirme que o pedido realmente vem daquela pessoa por um canal que não seja o e-mail. Resetar o 2FA para quem pedir é como a engenharia social contorna a proteção.

O e-mail não funciona e alguém precisa entrar agora

Você pode definir o secret do Google Authenticator de um usuário diretamente, pulando o link do e-mail. Gere um secret em base32, defina-o e adicione manualmente ao app autenticador:

SECRET=$(head -c 20 /dev/urandom | base32 | tr -d '=')
bin/magento security:tfa:google:set-secret john.smith "$SECRET"
echo "$SECRET"

A maioria dos apps autenticadores tem uma opção para digitar uma chave de configuração em vez de escanear um QR code. Use uma chave baseada em tempo. É uma ferramenta de recuperação para quem tem acesso ao servidor, então trate o secret como uma senha e não o cole em ferramentas de chat.

O código é sempre rejeitado

Os códigos baseados em tempo dependem do relógio. Se o relógio do servidor está dessincronizado, todos os códigos falham. Verifique se o horário do servidor está sincronizado com o NTP e se o celular usa horário automático. Isso causa mais logins falhos do que qualquer bug no módulo.

Desenvolvimento local

Em um ambiente local, digitar um código a cada login é chato, e o e-mail muitas vezes vai para um catcher como o Mailpit, então a primeira configuração fica desajeitada. Há duas opções limpas.

Use o secret pela CLI. Defina um secret do Google Authenticator para o seu usuário admin local com o comando acima e adicione ao seu app autenticador uma vez. Isso mantém o ambiente local mais próximo da produção.

Desabilite os módulos só localmente. Desde a 2.4.6, o módulo de dois fatores do Adobe IMS depende do módulo principal, então os dois precisam ser desabilitados juntos:

bin/magento module:disable Magento_AdminAdobeImsTwoFactorAuth Magento_TwoFactorAuth
bin/magento cache:flush

Isso grava no app/etc/config.php, que é commitado no repositório. Esse é o risco: um commit descuidado e a produção fica sem segundo fator. Se você o desabilitar localmente, mantenha as alterações do config.php fora dos seus commits, ou adicione uma checagem no pipeline de deploy que falhe quando o Magento_TwoFactorAuth estiver desabilitado. Algumas equipes usam um pequeno módulo só de desenvolvimento que desliga o 2FA pela configuração em vez de desabilitar o módulo, instalado como dependência de dev para nunca chegar à produção.

O setup de ambiente local que recomendo está no guia de Docker e Warden.

Acesso à API com 2FA habilitado

Com o módulo habilitado, o endpoint padrão de admin token não basta mais sozinho, porque um token deixaria um cliente pular o segundo fator. As integrações não são afetadas, já que usam seus próprios tokens e não estão ligadas a um login de admin. Para scripts que precisam de um admin token, o módulo oferece endpoints específicos por provider que recebem o nome de usuário, a senha e um código atual. Para o Google Authenticator:

curl -X POST "https://example.com/rest/V1/tfa/provider/google/authenticate" \
    -H "Content-Type: application/json" \
    -d '{"username":"api.user","password":"...","otp":"123456"}'

Para scripts sem supervisão isso é impraticável, porque ninguém está lá para digitar um código. Use uma integração com recursos limitados. Os trade-offs estão no artigo de autenticação da web API.

Conselhos operacionais

• Nunca desabilite o 2FA em produção para resolver um problema de suporte. Resete o usuário.
• Garanta que o e-mail transacional funciona e teste criando um novo usuário admin depois de toda mudança importante nas configurações de e-mail.
• Mantenha pelo menos duas pessoas com acesso total ao admin e 2FA funcionando, para que um celular perdido não deixe o negócio trancado do lado de fora. Alguém com acesso ao servidor sempre pode resetar pela CLI, mas isso deve ser o último recurso.
• Remova usuários do admin que não precisam mais de acesso. O 2FA protege contas, não decide quem deveria ter uma. O resto do checklist está no guia de hardening do admin.

FAQ

Posso desabilitar a autenticação em dois fatores no Magento 2?

Você pode desabilitar o módulo Magento_TwoFactorAuth e, desde a 2.4.6, também o Magento_AdminAdobeImsTwoFactorAuth. Faça isso só em desenvolvimento local, nunca em produção.

Como resetar o 2FA de um usuário admin do Magento?

Rode bin/magento security:tfa:reset com o nome de usuário e o código do provider, por exemplo google. O usuário configura o provider de novo no próximo login.

Por que os códigos do meu Google Authenticator são rejeitados?

Normalmente o relógio do servidor ou do celular está dessincronizado. Os códigos baseados em tempo só funcionam quando os dois relógios estão corretos, então confira o NTP no servidor.

As integrações do Magento precisam de autenticação em dois fatores?

Não. As integrações usam seus próprios tokens e não estão ligadas a um login de admin, então continuam funcionando. Dê a elas só os recursos de que precisam.

Atendo como freelancer em Magento e Adobe Commerce, incluindo configuração de segurança do admin. Se precisar de ajuda com isso, fale comigo.