Como Adicionar Autenticação de Dois Fatores ao Seu App

Para adicionar autenticação de dois fatores (2FA) ao seu app, permita que o usuário vincule um app autenticador escaneando um QR code, peça o código de seis dígitos que ele mostra depois da senha e só crie uma sessão completa no servidor quando esse código for validado. Dê a cada usuário códigos de recuperação de uso único quando ele ativar o recurso, limite quantas tentativas alguém pode fazer e exija a senha mais um código atual antes que o 2FA possa ser desligado. Se você usa um provedor de autenticação hospedado, ative a opção de multifator dele, em vez de construir a sua.

Este guia percorre as escolhas, o fluxo exato, prompts que você pode dar a um construtor com IA e os erros que fazem o 2FA parecer presente sem fazer nada. Se o conceito é novo para você, comece com o que é a autenticação de dois fatores.

Antes de começar: você precisa de um login funcionando

O 2FA fica sobre um login já existente. Você precisa de um destes primeiro:

• Um login próprio, com usuários e senhas com hash guardados no banco de dados do seu app.
• Um provedor de autenticação hospedado que gerencia os usuários para você.

Se ainda não tem nenhum dos dois, comece com como adicionar login ao seu app. O restante deste guia supõe que a etapa de senha já funciona.

Escolha o seu segundo fator

TOTP significa senha de uso único baseada em tempo (time-based one-time password), o padrão (RFC 6238) que os apps autenticadores usam. O seu servidor e o celular do usuário compartilham um segredo; cada um gera o mesmo código curto a partir desse segredo e do horário atual, geralmente trocando a cada 30 segundos. Não é preciso conexão de rede nem provedor de SMS.

Passkeys substituem ou complementam as senhas com uma chave criptográfica guardada no dispositivo do usuário. São mais fortes, mas dão mais trabalho para construir sozinho, então muitos apps começam com TOTP e adicionam passkeys depois, ou as obtêm de um provedor de autenticação.

Construir ou ativar?

Confira a documentação atual do seu provedor para saber quais fatores ele suporta e em quais planos. De qualquer forma, nunca escreva você mesmo a matemática de geração de códigos; use uma biblioteca amplamente utilizada.

Defina a política primeiro

Responda a estas perguntas antes de escrever o prompt, porque elas mudam o design:

1. Quem precisa usar? Opcional para todos, obrigatório para administradores e equipe, ou obrigatório para todos. Exigir para quem tem poder de administrador é comum. Veja controle de acesso baseado em funções.
2. Com que frequência o usuário digita um código? A cada login, ou uma vez por dispositivo por 30 dias ("lembrar deste dispositivo").
3. Quais ações exigem uma nova verificação? Trocar o e-mail, alterar dados de recebimento ou desligar o 2FA são bons candidatos. Isso se chama autenticação de reforço (step-up).
4. Qual é o processo para celular perdido? Códigos de recuperação, mais um procedimento manual de contingência que você esteja disposto a executar.

Passo a passo: 2FA com TOTP no seu próprio login

1. Guarde os campos certos

Cada usuário precisa de: se o 2FA está ativo, o segredo TOTP (criptografado em repouso, não em texto puro), a data em que foi ativado e uma lista de códigos de recuperação guardados com hash, como as senhas. Adicione também um lugar para contar as tentativas falhas.

2. Cadastro

1. O usuário abre as Configurações e clica em Ativar a autenticação de dois fatores.
2. O servidor gera um novo segredo e o devolve como QR code, além da versão em texto para quem não consegue escanear.
3. O usuário escaneia no app autenticador e digita o código atual.
4. O servidor verifica o código. Só se estiver correto ele salva o segredo e marca o 2FA como ativo.
5. O app mostra de 8 a 10 códigos de recuperação uma única vez e pede ao usuário que os guarde.

A etapa 4 é importante: ativar o 2FA antes de confirmar um código bloqueia quem escaneou errado.

3. Login com uma segunda etapa

1. O usuário envia e-mail e senha. O servidor os verifica.
2. Se o 2FA estiver ativo, o servidor não cria uma sessão completa. Em vez disso, cria um estado de "segundo fator pendente", de curta duração.
3. O app mostra a tela de código. O servidor verifica o código, com uma pequena janela de tolerância para diferença de relógio.
4. Só então o servidor emite a sessão real.

Cada rota protegida e cada endpoint da API precisa rejeitar o estado pendente. Uma tela de 2FA que só esconde páginas no navegador pode ser ignorada chamando a API diretamente.

4. Limites e alertas

Um código de seis dígitos tem um milhão de combinações, o que é adivinhável sem limites. Limite as tentativas, bloqueie a segunda etapa por um período após várias falhas e envie um e-mail ao usuário quando isso acontecer. Veja limitação de taxa e como enviar e-mails do seu app.

5. Recuperação e desligamento

• Um código de recuperação funciona uma única vez e depois é apagado.
• Desligar o 2FA exige a senha e um código atual ou um código de recuperação.
• Gerar novos códigos de recuperação invalida o conjunto antigo.
• Envie um e-mail ao usuário sempre que o 2FA for ativado ou desativado.

Prompts para dar ao seu construtor de IA

Comece pelo fluxo principal:

Adicione 2FA opcional usando app autenticador (TOTP) ao nosso login existente com e-mail e senha. Use uma biblioteca TOTP conhecida; não escreva o algoritmo você mesmo. Nas Configurações, mostre um QR code e o segredo em texto, e só ative o 2FA depois que o usuário digitar um código válido. Guarde o segredo criptografado e nunca o mostre de novo após a configuração. Mostre 10 códigos de recuperação de uso único uma vez e guarde-os com hash.

Depois, a aplicação, que é onde o código gerado mais costuma falhar:

Aplique o 2FA no servidor. Depois de uma senha correta, usuários com 2FA ativo recebem um estado pendente de curta duração, não uma sessão completa. Cada página e rota de API protegida deve rejeitar o estado pendente. Limite as tentativas de código a 5; depois bloqueie a segunda etapa por 15 minutos e envie um e-mail ao usuário.

Depois, a política:

Exija 2FA para contas de administrador: um administrador sem 2FA é enviado para a configuração e não pode acessar o painel até concluí-la. Exija a senha e um código atual para desligar o 2FA ou trocar o e-mail da conta. Envie um e-mail ao usuário quando o 2FA for ativado ou desativado.

Por fim, peça ao agente que explique o que construiu:

Liste cada rota que verifica se um segundo fator foi concluído, onde o segredo TOTP e os códigos de recuperação são guardados e como eles são protegidos.

Erros comuns

• Sessão emitida depois da senha. O erro mais grave. Se a sessão completa existe antes de o código ser verificado, o 2FA é só decoração. Teste chamando uma API protegida somente após a etapa de senha.
• Sem limite de tentativas. Chutes ilimitados tornam o código vulnerável a força bruta.
• Segredos ou códigos de recuperação em texto puro. Um vazamento do banco entrega o segundo fator de todos.
• Ativar antes de verificar. Usuários que escanearam errado ficam trancados no próximo login.
• Nenhum caminho de recuperação. Cada celular perdido vira um chamado de suporte ou um cliente perdido.
• Desligar fácil demais. Se uma sessão roubada pode desativar o 2FA sem código, a proteção acabou.
• Códigos em logs. Garanta que códigos e segredos nunca apareçam em logs do servidor ou em mensagens de erro.
• Verificar só na página de login. A redefinição de senha, o login por link mágico e qualquer login social também precisam respeitar o 2FA, ou viram uma forma de contorná-lo.

Checklist de testes

• O cadastro só é concluído depois de um código válido
• Login com senha correta mas sem código não dá acesso a nenhuma página ou API protegida
• Um código errado é rejeitado; tentativas erradas repetidas acionam o bloqueio e o e-mail
• Um código de alguns minutos atrás é rejeitado
• Cada código de recuperação funciona exatamente uma vez
• Desligar o 2FA exige a senha e um código atual
• A redefinição de senha não contorna o 2FA
• Administradores sem 2FA não acessam páginas de administração (se for exigido)
• Segredos e códigos de recuperação estão criptografados ou com hash no banco
• Nenhum código ou segredo aparece nos logs

Faça também a lista de segurança para apps criados com IA completa antes do lançamento.

Adicionando 2FA no Mythex

O Mythex não inclui um sistema de login integrado para os usuários finais do seu app, então o 2FA faz parte da abordagem de autenticação que você escolher: seu próprio login com e-mail e senha usando o banco do projeto, ou um provedor hospedado com suporte a multifator. Você descreve o que quer no chat com prompts como os acima, e as chaves do provedor vão para os segredos do projeto (por /secrets, nas configurações do projeto ou no cartão de segredos que o agente mostra), e não na caixa de mensagem. A receita da documentação Adicionar login ao seu app tem um prompt inicial, e Segurança para apps que você cria trata dos hábitos com chaves e permissões. Quando o agente terminar, teste cada item do checklist no Preview antes de publicar.

Perguntas