JWT costuma falhar não por fraqueza do formato, mas por validação parcial. O servidor decodifica o payload, encontra um user ID e segue adiante. Algoritmo, issuer, audience, expiração e política de chave ficam implícitos. Um token de segurança precisa de regras fechadas. Tudo que a aplicação deixa em aberto pode virar uma opção controlada pelo atacante.
Não aceite algoritmos escolhidos pelo token
O header informa um algoritmo, mas o verificador deve aceitar apenas os configurados. Algoritmo none e confusões entre chave simétrica e assimétrica já causaram vulnerabilidades reais.
Use wrappers internos com configuração explícita, em vez de repetir chamadas genéricas de biblioteca em cada endpoint.
Assinatura válida não basta
Um token pode estar corretamente assinado para outro cliente, API ou ambiente. Validar iss e aud impede que uma credencial legítima seja reutilizada no contexto errado.
exp e nbf também precisam ser aplicados. A assinatura garante integridade; claims definem aplicabilidade.
Não coloque segredos no payload
Base64URL é reversível. Dados pessoais, credenciais, detalhes internos e permissões excessivas podem vazar por logs, analytics e screenshots. Coloque apenas o mínimo necessário para o consumidor.
Se um dado precisa ser confidencial ou sempre atualizado, mantenha no servidor ou use um mecanismo diferente.
Tokens longos aumentam o impacto de roubo
Um access token válido por semanas oferece uma janela ampla. Durações curtas, refresh tokens revogáveis e reautenticação em ações sensíveis reduzem o risco.
A duração deve variar conforme o contexto. Uma API administrativa exige política mais restrita que leitura de conteúdo público.
Revogação precisa existir antes do incidente
Logout, mudança de senha, perda de dispositivo e suspensão de conta podem exigir invalidação. Um JWT stateless continuará válido até expirar se não houver blacklist, session version, introspection ou rotação de chave.
A escolha de esperar a expiração pode ser aceitável para tokens muito curtos, mas deve ser documentada.
Rotação de chave deve ser testada
O claim kid pode selecionar uma public key. A lookup precisa usar uma fonte confiável e não permitir path traversal, URLs arbitrárias ou chaves fornecidas pelo atacante. Durante a transição, verificadores podem precisar manter mais de uma chave.
Teste rotação em condições normais. Improvisar durante vazamento aumenta downtime e janela de abuso.
Ambientes precisam de separação
Um token de staging não deveria funcionar em produção. Issuer, audience e chaves distintas evitam essa mistura. Reutilizar segredo entre ambientes transforma um sistema menos protegido em caminho para o ambiente principal.
Testes automatizados devem provar que credenciais cruzadas são rejeitadas.
Armazenamento no cliente exige threat model
localStorage amplia impacto de XSS. Cookies HttpOnly exigem CSRF e SameSite. Mobile precisa de armazenamento protegido pelo sistema operacional. A decisão não pode ser tomada apenas pela facilidade da biblioteca.
Independentemente do local, previna XSS, use HTTPS e nunca registre tokens completos.
Refresh-token rotation reduz replay
Ao usar um refresh token, o servidor pode emitir um novo a cada uso e invalidar o anterior. Se o antigo reaparece, há sinal de replay ou corrida. A família de tokens pode ser revogada para proteger a sessão.
Essa estratégia exige armazenamento, transações e tratamento de requests concorrentes. Sem desenho claro, dois refreshes legítimos podem parecer ataque ou manter tokens antigos ativos.
Permissões não devem ficar obsoletas
Roles no token podem permanecer após mudança no servidor. Para operações críticas, consulte o estado atual ou use escopos de curta duração. Claims genéricos acumulam poder e dificultam auditoria.
Endpoints devem verificar escopo e contexto do recurso, não apenas presença de um usuário autenticado.
Observabilidade precisa ser segura
Registre motivo de rejeição, issuer, audience e identificador do token com redaction. Métricas de assinatura inválida, issuer desconhecido e audience incorreta podem indicar ataque ou rollout quebrado.
Tokens expirados costumam ser ruído normal; assinaturas inválidas merecem outro nível de alerta. Separar categorias melhora resposta.
Um plano de incidente fecha o ciclo
A equipe precisa saber como publicar nova chave, retirar a antiga, invalidar refresh tokens e acompanhar erros. O plano deve incluir comunicação e rollback.
Dependências devem ser mantidas
Bibliotecas JWT recebem correções de segurança e mudanças de defaults. Fixar uma versão antiga por anos mantém bugs conhecidos; atualizar sem testes pode alterar validação. O projeto precisa acompanhar advisories e executar vectors de regressão durante upgrades.
Evite implementar assinatura e parsing manualmente. O valor de uma biblioteca madura está tanto na criptografia quanto nas validações de formato e comparação.
Logs não podem virar um vazamento secundário
Proxies, APM e error trackers frequentemente capturam headers. Authorization deve ser redacted em todas as camadas. Para suporte, use jti, request ID e claims não sensíveis em vez de copiar a credencial inteira.
Auditorias periódicas devem procurar tokens em logs históricos e pipelines de analytics. Corrigir apenas a aplicação principal não basta quando intermediários continuam armazenando credenciais.
JWT seguro é um conjunto de decisões: algoritmo fechado, claims completos, chaves protegidas, vida curta, revogação e logs prudentes. A biblioteca é apenas uma parte.