Como decodificar um JWT e inspecionar suas declarações com segurança

Introdução

Um JSON Web Token (JWT, RFC 7519) é um formato de token compacto e seguro para URL usado para autenticação e autorização. Possui três partes codificadas em Base64URL separadas por pontos: header.payload.signature. O cabeçalho descreve o algoritmo, a carga contém declarações (ID do usuário, funções, expiração) e a assinatura prova que o token foi emitido por uma parte confiável. Crucialmente, o cabeçalho e a carga útil são codificados, não criptografados – qualquer pessoa pode lê-los.

Passo a passo

1. Divida o token em três partes

   Um JWT se parece com xxxxx.yyyyy.zzzzz. Divida no caractere de ponto para obter o cabeçalho (parte 0), carga útil (parte 1) e assinatura (parte 2). Se não houver exatamente três partes, o token está malformado.

2. Base64URL decodifica o cabeçalho

   O cabeçalho é um objeto JSON codificado em Base64URL como {"alg":"HS256","typ":"JWT"}. Base64URL usa - e _ em vez de + e/e omite o preenchimento. Decodifique-o e JSON.parse para ler o algoritmo e digitar. Nosso decodificador JWT faz isso automaticamente.

3. Base64URL decodifica a carga útil (reivindicações)

   A carga útil é um objeto JSON de reivindicações. As reivindicações registradas incluem iss (emissor), sub (assunto), aud (público), exp (expiração), nbf (não antes), iat (emitido em) e jti (id de token). As declarações privadas são específicas do aplicativo (por exemplo, função, email). Decodifique e inspecione, mas não confie até ser verificado.

4. Verifique o vencimento e as reivindicações não anteriores

   exp e nbf são carimbos de data/hora Unix (segundos). Se o tempo atual tiver passado de exp, o token expirou e deve ser rejeitado. Se a hora atual for anterior ao nbf, o token ainda não é válido. Verifique se há UX no lado do cliente, mas aplique-os no lado do servidor para segurança.

5. Verifique a assinatura no servidor (nunca no lado do cliente)

   A assinatura é HMAC-SHA256(secret, header.payload) para HS256 ou assinatura RSA/ECDSA para RS256/ES256. A verificação requer a chave secreta ou pública, que nunca deve chegar ao navegador. Use uma biblioteca como jsonwebtoken (Node) ou jose para verificar – nunca escreva sua própria criptografia.

Exemplos

Problemas comuns

• Tratar a decodificação como verificação: qualquer um pode criar um JWT com qualquer reivindicação e uma assinatura falsa. A decodificação lê a carga útil, mas não prova nada. Sempre verifique a assinatura com a chave secreta/pública no servidor antes de confiar nas declarações.
• Usando o algoritmo 'none': a especificação JWT permite alg: none para tokens não seguros. Se o seu verificador aceitar alg: none, um invasor poderá falsificar tokens. Configure sua biblioteca para rejeitar nenhum algoritmo esperado e colocar na lista de permissões.
• Armazenando JWTs em localStorage: XSS pode ler localStorage e exfiltrar tokens. Prefira cookies httpOnly, Secure, SameSite=Strict para tokens de sessão ou tokens de memória de curta duração com um cookie de token de atualização.
• Não verificar exp/aud/iss: um token roubado é válido até expirar. Sempre verifique exp (expiração), aud (público-alvo) e iss (emissor) em cada solicitação para evitar a repetição do token entre serviços.

Dicas

• Use tokens de acesso de curta duração (15 minutos) mais tokens de atualização de longa duração — isso limita a janela se um token de acesso for roubado.
• Prefira RS256 (assimétrico) a HS256 (simétrico) quando vários serviços verificam tokens: cada serviço obtém a chave pública e apenas o emissor possui a chave privada.
• Use nosso decodificador JWT durante o desenvolvimento para inspecionar o que o servidor está emitindo - ele mostra o cabeçalho decodificado, a carga útil e um resumo de declaração legível por humanos sem enviar o token a qualquer lugar.
• Nunca coloque dados confidenciais (senhas, PII) em uma carga útil JWT — ela é codificada em Base64, não criptografada, e qualquer pessoa que interceptar o token pode ler todas as declarações.

Ferramentas relacionadas

• JWT Decoder — Decode JWT tokens and inspect the header and payload. See the decoded JSON content instantly.
• Base64 Encode & Decode — Encode and decode Base64 with UTF-8 support. Instant, private, browser-based. No upload, no signup.
• Hash Generator — Generate SHA-256, SHA-1, SHA-512 and SHA-384 hashes from any text. Uses Web Crypto API, fully private.
• URL Encode & Decode — Encode and decode URL (percent-encoding) with UTF-8 support. Instant, private, browser-based. No upload, no signup.
• Formatador JSON — Formate, embeleze e valide JSON instantaneamente no seu navegador. Sem upload, totalmente privado.
• AES 256 Ver Entschlüsseln online Kostenlos, Im navegador — AES 256 Ver Entschlüsseln online Kostenlos, Im navegador online grátis. Processa dados instantaneamente no seu navegador. Sem upload, sem cadastro, totalmente privado.
• AES texto Encrypter Decrypter — AES texto Encrypter Decrypter online grátis. Processa dados instantaneamente no seu navegador. Sem upload, sem cadastro, totalmente privado.
• ASCII Table Reference — Browse the full ASCII table with decimal, hex, octal, and binary values in your browser. Free, online, no upload.

Guias Relacionados

• Como codificar e decodificar Base64: um guia completo
• Algoritmos de hash explicados: MD5, SHA-1, SHA-256, SHA-512

Referências

• RFC 7519 —JSON Web Token (JWT) — Official JWT specification
• RFC 7515 —JSON Web Signature (JWS) — How JWT signatures are computed
• jwt.io —JWT Debugger — Interactive JWT debugger by Auth0