JWT decodificador: o que está dentro de um token e o que não

As três partes

• Cabeçalho — o algoritmo de assinatura (`alg`) e o tipo de token (`typ`), por exemplo HS256.
• Carga útil — as reivindicações: de quem se trata o token, quando foi emitido e quando expira.
• Assinatura – calculada nos dois primeiros segmentos com a chave do emissor, razão pela qual um decodificador a mostra, mas não pode verificá-la.

                eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 . eyJzdWIiOiIxMjMiLCJleHAiOjE3NjAwMDAwMDB9 . signature
           header                            payload                       signature
              

As afirmações que explicam a maioria das falhas

• `exp` (expiração) — a causa mais comum de um 401. Um token que expirou há dois minutos é rejeitado antes que qualquer outra coisa seja examinada.
• `nbf` (não antes) — a imagem espelhada: um token usado antes de sua janela de validade ser rejeitado.
• `iat` (emitido em) — útil para calcular a idade de uma sessão e para detectar relógios que discordam.
• `aud` (público) e `iss` (emissor) — incompatibilidades aqui significam que o token é válido, mas foi emitido para um serviço diferente, que falha de maneira confusa.

As reivindicações de tempo são segundos UTC desde a época Unix. Se um token parecer válido, mas expirar muito cedo ou tarde demais, verifique se há um problema de relógio ou uma carga transportando milissegundos onde segundos eram esperados.

Por que você nunca deve confiar cegamente em `alg`

Dois ataques têm idade suficiente para serem famosos e ainda aparecerem na natureza. O algoritmo `none` informa ao verificador que não há assinatura alguma; um servidor que lê o cabeçalho em vez de impor seu próprio algoritmo esperado o aceita. E na confusão RSA/HS, um invasor assina com a chave pública como um segredo HMAC, enganando um servidor que aceita ambas as famílias. A defesa em ambos os casos reside no verificador, não no decodificador: fixa o algoritmo esperado no lado do servidor e nunca o deriva do próprio token.

Decodifique localmente, sempre

Um JWT é uma credencial: quem a possui pode atuar como usuário até que ela expire. Colar um real em um site que o publica em um servidor entrega uma sessão ao vivo sem nenhum benefício, já que a decodificação é uma aritmética base64url que qualquer navegador pode fazer em microssegundos. O decodificador YamlBox JWT analisa o token na página, mostra as declarações de carimbo de data/hora como datas UTC legíveis e continua trabalhando com a rede desativada — o único tipo de decodificador que vale a pena usar em um token de produção.

Uma rotina de depuração que funciona

1. Decodifique e leia `exp` primeiro — metade de todos os relatórios de “token inválido” termina aqui.
2. Verifique `aud` e `iss` em relação ao que API espera e depois `nbf` para verificar a distorção do relógio.
3. Compare as declarações decodificadas com o que seu código assume sobre funções ou escopos.
4. Se as declarações parecerem corretas e ainda assim falharem, o problema é a verificação – chave errada, segredo girado ou incompatibilidade de algoritmo.