O que tem dentro de um JWT, e por que decodificar não é verificar

Um JWT (JSON Web Token) é a string longa que mantém você conectado em muitos apps web e APIs. Ele parece criptografado, mas na maioria dos casos não é: quem tem o token consegue ler o que está dentro.

Três partes separadas por pontos

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3q2-7w…
└ header ──────────┘ └ payload ───────┘ └ signature

O header diz como o token é assinado, por exemplo HS256 ou RS256. O payload guarda as claims: quem é o usuário (sub), quando o token foi emitido (iat) e quando expira (exp), além do que o app acrescentar, como perfis de acesso. Os dois são JSON codificado em base64url, que é uma codificação, não criptografia.

O que importa é a assinatura

A terceira parte é uma assinatura sobre as duas primeiras, feita com um segredo ou uma chave privada. Só um servidor com a chave certa consegue conferi-la. Se alguém muda um único caractere do payload, por exemplo o perfil de user para admin, a assinatura deixa de bater.

Decodificar não é verificar

Um token que decodifica sem erro diz o que afirma, não se é verdade. O seu backend precisa verificar a assinatura com a chave, rejeitar tokens cujo exp já passou e aceitar só os algoritmos esperados, nunca “none”. As bibliotecas de JWT fazem isso por você; pular essa etapa é uma vulnerabilidade clássica.

Regras práticas

Não coloque segredos como senhas no payload, porque ele é legível. Use prazos de expiração curtos. Trate o token como uma senha enquanto ele for válido: quem copiá-lo pode usá-lo até expirar.

Onde guardar um token no navegador

Qualquer script da página consegue ler o que está no localStorage, então uma única falha de cross-site scripting (XSS) pode vazar o token. Um cookie HttpOnly não pode ser lido pelo JavaScript, o que elimina esse risco; combine-o com os atributos Secure e SameSite e com proteção contra falsificação de solicitações entre sites (CSRF). Não existe opção perfeita, mas para tokens de sessão os cookies HttpOnly são o padrão mais seguro.

Expiração e tokens de atualização

Um JWT não pode ser "deslogado" sozinho: ele continua válido até o exp, a menos que o servidor mantenha uma lista de revogação. Por isso os tokens de acesso costumam durar minutos, não dias. Um token de atualização de vida mais longa, guardado com mais cuidado e verificado no servidor, é usado para obter um novo token de acesso quando o antigo expira.

Os claims mais comuns num relance

iss  emissor        quem criou o token
sub  sujeito        o usuário ou cliente a que se refere
aud  público        qual serviço deve aceitá-lo
exp  expiração      horário Unix a partir do qual é inválido
nbf  não antes de   horário Unix antes do qual é inválido
iat  emitido em     horário Unix em que foi criado

Os claims de tempo são timestamps Unix em segundos. O servidor deve verificar aud além de exp: um token válido emitido para um serviço não deve ser aceito por outro.

Lendo um token

O decodificador de JWT da 4Dev separa o token em partes e mostra o header e o payload como JSON legível. Ele só decodifica e não confere a assinatura. O token é enviado ao servidor da 4Dev para ser decodificado e não é registrado nem guardado, mas evite colar tokens reais de produção e revogue qualquer token que você ache que vazou.

Abrir o decodificador de JWT