Decodificar vs verificar JWT: o que checar
Decodifique um JWT para inspecionar claims, mas verifique a assinatura e as regras de confiança antes de usar em autorização.
JWTs são fáceis de colar em um decodificador, o que ajuda na depuração. O risco é tratar o JSON decodificado como prova de que o token é confiável.
Decodificar responde: o que este token declara? Verificar responde: um emissor confiável assinou este token exato para esta audience, nas regras que minha aplicação espera?
O que a decodificação mostra
Um decodificador pode inspecionar a estrutura:
- Campos do header como
alg,typekid. - Claims do payload como
sub,iss,aud,exp,iatenbf. - Se header e payload são JSON válido em Base64URL.
- Se claims de tempo parecem expirados, no futuro ou afetados por skew de relógio.
Isso basta para muitos relatos de usuário. Se a requisição falha com 401, você pode checar rapidamente expiração, audience diferente ou claim ausente no backend.
O que a decodificação não prova
Claims decodificados ainda são só texto até a verificação. Um desenvolvedor pode editar o payload, recodificar e colar uma string com cara de token na requisição.
A verificação deve checar:
- Assinatura com a chave ou chave pública correta.
- Algoritmo esperado, sem aceitar algoritmos mais fracos por engano.
- Emissor que o serviço confia.
- Audience ou client ID pretendidos.
- Janelas de
expenbf. - Regras de autorização específicas da aplicação.
Isso pertence ao backend, API gateway, middleware de identidade ou biblioteca de auth confiável.
Sequência prática de depuração
Quando surgir um problema com JWT, comece pela inspeção:
- Decodifique localmente com o Decodificador JWT.
- Confirme três segmentos no token.
- Leia
iss,aud,sub,exp,iatenbf. - Converta claims de tempo com o Conversor de timestamp se os horários parecerem estranhos.
- Veja nos logs do backend o erro exato de verificação.
Só depois ajuste chaves de assinatura, provedor de identidade ou configuração de middleware.
Erros comuns
O mais frequente é aceitar token só decodificado no código da aplicação, sem verificação. Outro é checar assinatura mas pular iss ou aud, permitindo token válido do sistema errado.
Desenvolvedores também caem em skew de relógio: o token pode ser válido no IdP e ainda inválido em um servidor com relógio atrasado. Pequenas janelas de tolerância ajudam, mas devem ser explícitas.
Modelo mental seguro
Use decodificar para visibilidade. Use verificar para confiança. Use regras de autorização para acesso.
São três passos distintos; mantê-los separados deixa a depuração de JWT bem menos confusa.