O que é TOTP e o que é 2FA neste contexto
TOTP (Time-based One-Time Password) é o algoritmo por trás da maioria dos apps autenticadores: um segredo compartilhado + o relógio Unix produzem um código de curta duração. 2FA (autenticação de dois fatores) é o produto de segurança maior — TOTP é uma forma comum de implementar o segundo fator. Esta página é um laboratório do algoritmo TOTP para desenvolvedores, não um tutorial de ativar 2FA em um serviço específico.
Por que meu código TOTP não bate
Quando o backend rejeita o código, a causa quase nunca é “sorte” — é parâmetro ou relógio. Use os três períodos lado a lado: se o código do app bate no anterior ou seguinte, você tem desvio de relógio (NTP no servidor, fuso errado, drift no celular). Confira também algoritmo (SHA-1 vs SHA-256), dígitos (6 vs 8), período (30 vs 60) e se o segredo foi tratado como Base32 (não Base64).
Como usar o playground
- Gere um segredo de teste ou cole um Base32 / URI
otpauth://. - Veja o código atual e a contagem regressiva; compare com o autenticador.
- No modo verificação, cole o código que o backend recebeu e ajuste a janela ±N.
- Monte a URI para testar no app. Para entender o HMAC por baixo, abra o Gerador de HMAC (TOTP é HMAC do contador de tempo).
Como validar TOTP no backend
Guarde o segredo (em Base32 ou bytes) com o usuário, calcule TOTP no servidor com o mesmo algoritmo, dígitos e período, e compare o código enviado com a janela ±1 (três valores). Use comparação em tempo constante quando possível, registre falhas e limite tentativas. Nunca confie só no relógio do cliente. O JWT do login e o HMAC de webhooks resolvem outras partes do fluxo de auth — veja também o JWT Decode & Encode.
Base32 não é Base64
O segredo TOTP usa Base32 (A–Z, 2–7). Base64 é outro alfabeto, comum em JWT e em hashes. Confundir os dois é uma causa frequente de “código nunca bate”. Para Base64 genérico, use o Codificador Base64.