Skip to content

Login em Duas Etapas (2FA) ​

Segundo fator de autenticação opcional, escolhido pelo próprio usuário nas configurações da conta. Padrão: vazio — nenhuma validação extra, até o usuário ativar e confirmar um método.

Métodos ativáveis (novos): SMS ou Google Authenticator (TOTP) — TwoFactorMethod::selectable(). email continua existindo como valor válido do enum (login/reenvio de quem já tinha ativado antes dessa restrição continuam funcionando normalmente), mas não é mais oferecido em POST account/two-factor/setup (§3).

SMS só pode ser ativado depois que o telefone é verificado — fluxo novo de verificação de telefone (§3.1), independente do 2FA em si.

Envio de código (e-mail e SMS) é sempre SÍNCRONO — nunca fila/job. A chamada ao provedor (SES/AWS Notify) acontece dentro da própria requisição e só é considerada "enviada" depois que o provedor confirma; falha vira TwoFactorException/PhoneVerificationException (nunca vaza a exceção crua). Ver TwoFactorService::sendEmailCode()/sendSmsCode().

Implementado em App\Services\TwoFactor\TwoFactorService (orquestração) + App\Services\TwoFactor\TotpService (TOTP puro, RFC 6238, sem dependência de Composer), App\Services\Phone\PhoneVerificationService (verificação de telefone), App\Http\Controllers\Access\AuthController (desafio de login), App\Http\Controllers\Access\TwoFactorSettingsController (ativar/desativar nas configurações) e App\Http\Controllers\Access\PhoneVerificationController (verificar telefone).


1. Modelo de dados ​

users (colunas novas) ​

  • two_factor_method (string, nullable): null | email | sms | google (email só chega aqui por ativações antigas — não é mais selecionável).
  • two_factor_secret (text, nullable, hidden na serialização): segredo TOTP em base32 — só preenchido para google, só depois de confirmado.
  • two_factor_confirmed_at (timestamp, nullable).
  • phone_verified_at (timestamp, nullable, nova): preenchido só por PhoneVerificationService::confirm(), junto com phone na mesma atualização. User::boot() zera automaticamente phone_verified_at sempre que phone muda sem que phone_verified_at também mude na mesma gravação — garante que "verificado" sempre se refere ao número atual, mesmo que phone seja alterado por outro caminho no futuro (edição de perfil, por exemplo). User::hasVerifiedPhone(): bool.

2FA só é exigido no login se as duas colunas estiverem preenchidas (User::hasTwoFactorEnabled(): two_factor_method !== null && two_factor_confirmed_at !== null). startSetup() (§3) não toca em nenhuma das duas — só confirmSetup() as preenche, depois do código validado — então um setup começado e nunca confirmado nunca deixa o usuário travado fora da própria conta.

two_factor_challenges (tabela nova) ​

Um registro por vez, por user_id + purpose (o service sempre apaga qualquer desafio anterior do mesmo par antes de criar um novo):

ColunaUso
tokenOpaco, devolvido ao cliente — nunca o id numérico.
purposelogin (depois da senha), setup (ativar nas configurações) ou phone_verification (verificar telefone antes de ativar SMS).
methodemail | sms | google.
code_hashHash (Hash::make) do código de 6 dígitos — só e-mail/SMS/verificação de telefone.
pending_secretSegredo TOTP recém-gerado, só purpose=setup + method=google — não vai para users até confirmar.
pending_phoneTelefone normalizado aguardando confirmação, só purpose=phone_verification — só vira users.phone depois do código certo.
device_nameSó purpose=login — replica a bifurcação dashboard_sass/UserAccount de AuthController na hora de emitir o token final.
attemptsMáx. 5 (TwoFactorService::MAX_ATTEMPTS) — estourou, desafio é apagado e o cliente precisa recomeçar.
expires_at10 minutos (TwoFactorService::CODE_TTL_MINUTES).

2. Fluxo de login ​

POST auth/login { email, password }
  → sem 2FA confirmado: mesmo token de sempre (nada muda)
  → com 2FA confirmado: { two_factor_required: true, method, challenge_token, expires_at }

POST auth/login/two-factor/verify { challenge_token, code }   (throttle 10/min)
  → código certo: mesmo token que auth/login devolveria sem 2FA
  → código errado/expirado: 422 { error: "..." }

POST auth/login/two-factor/resend { challenge_token }         (throttle 5/min)
  → só para email/sms — reenvia um código novo, zera as tentativas
  → google: 422 (o app já gera um código novo sozinho a cada 30s)

AuthController::issueLoginResponse() (privado) concentra a emissão do token — extraído do login() original, reaproveitado por verifyTwoFactor(), garantindo que os dois caminhos (com e sem 2FA) emitam exatamente o mesmo formato de resposta.


3. Fluxo de configuração (account/two-factor*, autenticado) ​

GET account/two-factor
  → { method, confirmed, email, phone, phone_verified }   (nunca o segredo TOTP)

POST account/two-factor/setup { method: 'sms' | 'google' }
  → sms/google só (email não é mais aceito aqui — 422 "Método não
    disponível para ativação. Escolha SMS ou Google Authenticator." —
    TwoFactorMethod::selectable())
  → sms: manda o código na hora, devolve { challenge_token }
  → google: gera um segredo novo (ainda não salvo no usuário), devolve
    { challenge_token, secret, otpauth_uri } — o front renderiza o QR Code
    a partir de otpauth_uri (client-side; o segredo nunca sai para um
    serviço externo de geração de QR)

POST account/two-factor/confirm { challenge_token, code }
  → código certo: ativa (two_factor_method + two_factor_secret [google] +
    two_factor_confirmed_at = now())
  → código errado/expirado: 422

DELETE account/two-factor { current_password }
  → exige a SENHA ATUAL, não um código de 2FA — evita travar quem perdeu
    acesso ao próprio método (celular perdido, número trocado, etc.)

sms exige que o usuário já tenha o telefone verificado (User::hasVerifiedPhone(), 422 "Verifique seu telefone antes de ativar a verificação por SMS." se não tiver) — ver §3.1 para o fluxo de verificação.

3.1 Verificação de telefone (account/phone-verification*, autenticado) ​

Pré-requisito para ativar 2FA por SMS — mas é um fluxo independente (o telefone pode ser verificado sem nunca ativar 2FA). Reaproveita a tabela two_factor_challenges com purpose=phone_verification (App\Services\Phone\PhoneVerificationService).

POST account/phone-verification/start { phone }         (throttle 5/min)
  → normaliza o telefone (só dígitos, mínimo 10), manda o código por SMS
    na hora (Notify, mesmo caminho do 2FA) — NÃO altera users.phone ainda
  → falha ao enviar: 422, desafio é apagado (não fica pendência órfã)

POST account/phone-verification/confirm { code }        (throttle 10/min)
  → código certo: grava phone + phone_verified_at juntos (User::boot()
    exige isso — ver §1) e apaga o desafio
  → código errado: 422, incrementa attempts (máx. 5, depois disso o
    desafio é apagado e é preciso chamar /start de novo)
  → expirado/sem desafio pendente: 422

POST account/phone-verification/resend                  (throttle 5/min)
  → reenvia para o mesmo pending_phone do desafio atual (chama /start de
    novo internamente) — 422 se não houver verificação pendente

Validação do código/estado é toda no backend (PhoneVerificationService) — o front só conduz a interface (campos de telefone/código, contagem de tentativas/expiração vindas dos erros 422).

O envio em si é via AWS End User Messaging Notify (App\Services\AwsEndUserMessagingSmsService::sendVerificationCode(), Aws\PinpointSMSVoiceV2\PinpointSMSVoiceV2Client::sendNotifyTextMessage()) — um template pré-aprovado da AWS (texto/idioma já prontos, ex.: notify-code-verification-portuguese-brazil-007), só o código é substituído. Não confundir com "Amazon SNS → Text messaging (SMS)" (Aws\Sns\SnsClient::publish()) — são dois produtos AWS diferentes para mandar SMS, cada um com seu próprio sandbox/verificação de número/origem; usar o errado (SNS) parece funcionar (a chamada tem sucesso) mas nunca entrega.

Exigiu atualizar aws/aws-sdk-php — a versão instalada quando o End User Messaging "cru" (sendTextMessage) foi implementado não tinha nenhuma operação *Notify* ainda (recurso recente da AWS); composer update aws/aws-sdk-php --with-dependencies trouxe pra 3.397.0, dentro da mesma faixa ^3.316 do composer.json (sem mudança de constraint).

Reaproveita as credenciais AWS já usadas para S3 (config/services.php → aws_sms) — a chave IAM precisa também ter sms-voice:SendNotifyTextMessage liberado. AWS_SMS_NOTIFY_CONFIGURATION_ID (.env) é obrigatório — o ID/ARN de uma configuração Notify já criada no console (use case "Code verification"), com status ACTIVE. AWS_SMS_NOTIFY_TEMPLATE_ID é opcional (default notify-code-verification-portuguese-brazil-007). AWS_SMS_ORIGINATION_IDENTITY/AWS_SMS_REGION continuam existindo só pro envio "cru" de teste (sms:test sem --notify) — o 2FA não usa mais. Falha no envio (credenciais ausentes, configuração não encontrada, número inválido, etc.) vira TwoFactorException — nunca vaza a exceção crua da AWS pro usuário.

Testar a integração sem passar pelo login/2FA:

php artisan sms:test 11987654321 --notify

Manda um código de teste pelo mesmo caminho que o 2FA usa de verdade, mostra o erro exato da AWS se falhar, e confirma se o número de destino já está verificado (ver abaixo). Se AWS_SMS_NOTIFY_CONFIGURATION_ID estiver vazio, lista as configurações Notify e os templates já disponíveis na conta (com status/idioma/países) em vez de tentar enviar às cegas. Sem --notify, o comando testa o envio "cru" (sendTextMessage + AWS_SMS_ORIGINATION_IDENTITY) — útil pra isolar se o problema é geral (credenciais/conta) ou específico do Notify (configuração/template).

"Enviou com sucesso mas não chegou no celular": quase sempre é o número de destino não estar verificado — contas novas de End User Messaging só entregam pra destinos verificados manualmente, mesmo que o envio retorne sucesso. sms:test checa isso sozinho depois de um envio "bem-sucedido". Pra verificar um número direto do terminal (a AWS manda um código de verdade por SMS, você confirma na hora):

php artisan sms:test 11987654321 --verify

Manual, no console AWS: End User Messaging → Verified destination phone numbers (verificar o número) — ou pedir saída do modo restrito nas configurações da conta, se disponível para a região.


4. TOTP (Google Authenticator) — TotpService ​

Implementação própria, em PHP puro (HMAC-SHA1, 6 dígitos, período de 30s — o padrão que Google Authenticator/Authy/1Password esperam), em vez de uma dependência de Composer (pragmarx/google2fa etc.): adicionar uma lib exigiria rodar composer update para regravar o composer.lock, indisponível neste ambiente (sem PHP instalado).

Algoritmo conferido manualmente contra o vetor de teste oficial da RFC 6238 (Apêndice B — segredo ASCII "12345678901234567890", T=59 → código de 6 dígitos 287082, os últimos 6 dígitos do valor de 8 dígitos que o apêndice mostra) — reproduzido em tests/Unit/TotpServiceTest.php e também verificado à parte em Python (hmac/hashlib) antes de escrever a versão PHP; os dois batem com o vetor oficial.

verify() aceita ±1 período (30s) de tolerância, para relógios de celular levemente dessincronizados.


5. O que não foi feito ​

  • Recuperação de conta: se o usuário perder acesso ao método de 2FA (celular com o Authenticator, número de SMS, e-mail), não há fluxo de auto-recuperação (códigos de backup, por exemplo) — hoje só dá para desativar manualmente no banco (users.two_factor_method = null etc.), via suporte. Não foi pedido nesta etapa.
  • Front-end: fastgivr-portal — tela de login com a segunda etapa, tela de verificação de telefone e a tela de configuração (ativar SMS/Google, confirmar, desativar) no Perfil, com sms habilitado no seletor de método (hoje desabilitado no front até essa etapa ser concluída) e email removido das opções de ativação.