GameParticles
Desenvolvimento

Como decodificar um JWT e ler as claims com segurança

Decodifique um JWT separando os três segmentos base64url, leia claims como iss, sub e exp e entenda por que decodificar um token não é o mesmo que verificá-lo.

Atualizado

Um JWT são três segmentos codificados em base64url e separados por pontos: cabeçalho, payload e assinatura. Para ler as claims, separe em ., decodifique os dois primeiros segmentos de base64url e faça o parsing do JSON resultante. Decodificar não exige chave, mas também não prova nada; só a verificação da assinatura diz que o token é genuíno.

Anatomia de um token

Um JWT típico tem esta cara: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IkFkYSIsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c. As três partes são:

  • Cabeçalho: {"alg":"HS256","typ":"JWT"}. Informa qual algoritmo assinou o token e, opcionalmente, um id de chave (kid).
  • Payload: {"sub":"1234","name":"Ada","iat":1516239022}. As claims, que são os dados que realmente interessam a você.
  • Assinatura: bytes produzidos ao assinar header.payload com a chave do emissor. Não é JSON, então não se decodifica em nada legível.

Todo cabeçalho de JWT começa com eyJ porque é nisso que {" é codificado em Base64. Se você vir eyJ, é quase certo que está olhando para um JWT.

Decodificando à mão

Os segmentos usam base64url, não o Base64 padrão: - em vez de +, _ em vez de /, e sem o preenchimento com =. A maioria dos decodificadores aceita o alfabeto seguro para URLs, mas alguns insistem no preenchimento. Para decodificar em uma ferramenta rigorosa, substitua os caracteres e acrescente = até o tamanho ser múltiplo de quatro. Depois decodifique, e você tem o texto JSON.

Em JavaScript, a versão rápida é JSON.parse(atob(token.split(".")[1].replace(/-/g,"+").replace(/_/g,"/"))). Em Python, base64.urlsafe_b64decode(seg + "=" * (-len(seg) % 4)) cuida da aritmética do preenchimento para você. Na linha de comando, cut -d. -f2 | base64 -d funciona depois que o preenchimento é corrigido.

Se você só quer ver o que há dentro sem escrever código, cole o token no Decodificador de JWT. Ele separa os segmentos, decodifica o cabeçalho e o payload, explica cada claim padrão e mostra uma contagem regressiva até a expiração.

Para inspecionar você mesmo os bytes de um único segmento, solte-o no decodificador Base64 depois de corrigir o preenchimento; a saída é o texto JSON bruto.

As claims que você vai encontrar

As claims registradas são nomes curtos definidos na RFC 7519. As mais comuns:

  • iss (issuer, emissor): quem criou o token, normalmente uma URL como https://accounts.example.com.
  • sub (subject, sujeito): o usuário ou a entidade a que o token se refere.
  • aud (audience, público): a quem o token se destina. Sua API deve rejeitar tokens cujo aud não corresponda a ela.
  • exp (expiration, expiração): timestamp Unix em segundos, depois do qual o token é inválido.
  • nbf (not before, não antes de): o token é inválido antes desse horário.
  • iat (issued at, emitido em): quando ele foi criado.
  • jti: id único do token, usado para evitar replay.

Todo o resto é personalizado: email, roles, scope, tenant_id e assim por diante. Claims personalizadas significam o que o emissor disser que significam, então consulte a documentação do seu provedor de identidade em vez de adivinhar.

Os timestamps estão em segundos, não em milissegundos. 1516239022 é 18 de janeiro de 2018. Um valor como 1516239022000 é um bug no lado do emissor e será lido por qualquer validador correto como uma data a dezenas de milhares de anos de distância.

Decodificar não é verificar

Esta é a parte em que as pessoas erram. Qualquer um pode montar um token com {"sub":"admin","roles":["superuser"]} no payload e uma string qualquer no lugar da assinatura. Ele é decodificado perfeitamente. E também não vale nada, a menos que a assinatura confira com a chave do emissor.

A verificação depende de alg:

  • HS256, HS384, HS512: HMAC com um segredo compartilhado. O verificador precisa do mesmo segredo que o emissor usou. A assinatura é um digest HMAC-SHA de header.payload; um gerador de hash mostra como é um digest SHA-256 simples, mas o HMAC também mistura a chave, então a verificação deve ficar em uma biblioteca no seu servidor.
  • RS256, ES256, PS256: assimétricos. O emissor assina com uma chave privada; você verifica com a chave pública, normalmente obtida de um endpoint JWKS, como /.well-known/jwks.json, e localizada pelo kid.
  • none: sem assinatura. Rejeite esses tokens de imediato.

Use uma biblioteca bem mantida (jsonwebtoken ou jose no Node, PyJWT no Python, java-jwt na JVM) e passe a ela a lista de algoritmos esperados, o emissor e o público. Nunca deixe o cabeçalho alg do próprio token decidir como ele é verificado; essa é a raiz de várias falhas de bypass do mundo real.

Decodifique para depurar. Verifique para confiar. Uma claim decodificada é uma pista do que o emissor pretendia, não prova de coisa alguma, até que a assinatura tenha sido conferida no servidor.

Manuseio seguro durante a depuração

Um JWT é uma credencial ao portador: quem o tiver em mãos pode usá-lo até que expire. Cole tokens apenas em ferramentas que rodam no navegador e não os transmitem. Prefira tokens expirados ou de um ambiente de staging ao compartilhar em tickets. Remova o segmento da assinatura antes de postar um token em um chat; os dois primeiros segmentos ainda mostram as claims, e o token deixa de ser utilizável.

Mais ferramentas de decodificação e inspeção estão na categoria de desenvolvedor.

Experimente

Cole um token no Decodificador de JWT para ver o cabeçalho, cada claim com uma breve explicação, o algoritmo de assinatura e quanto tempo falta até exp. Nada sai do seu navegador.

Ferramentas deste guia

Perguntas frequentes

Por que todo JWT começa com eyJ?

Porque o cabeçalho é um JSON que começa com uma chave de abertura e aspas duplas, e os caracteres {" são codificados como eyJ em Base64. O mesmo prefixo normalmente aparece também no início do segmento do payload.

Posso verificar a assinatura de um JWT no navegador?

Você só consegue verificar um token RS256 ou ES256 se tiver a chave pública do emissor. Tokens HS256 precisam do segredo compartilhado, que nunca deveria estar em um navegador. Na prática, verifique no servidor com uma biblioteca bem mantida.

A claim exp está em segundos ou em milissegundos?

Em segundos desde a época Unix, conforme a RFC 7519. Um valor de 13 dígitos é um timestamp em milissegundos e indica um bug no lado emissor.

É seguro colar um JWT em um decodificador online?

Só se o decodificador rodar no lado do cliente e não enviar nada a um servidor. Mesmo assim, prefira tokens expirados ou de staging, porque um JWT ativo é uma credencial ao portador que funciona para qualquer pessoa que a tenha em mãos.

Mais guias para desenvolvedores

Formatador de JSON
Desenvolvimento · Formate, valide e minifique JSON com realce de sintaxe.
↵
Codificar / decodificar Base64
Desenvolvimento · Codifique texto em Base64 ou decodifique Base64 para texto simples.
↵
Codificador / Decodificador de URL
Desenvolvimento · Codifique ou decodifique componentes de URL e query strings.
↵
Gerador de hash
Desenvolvimento · Gere hashes MD5, SHA-1, SHA-256 e SHA-512.
↵
Gerador de UUID
Desenvolvimento · Gere UUIDs v4 (aleatórios) em massa com um clique.
↵
Testador de regex
Desenvolvimento · Teste expressões regulares em um texto com destaque das correspondências ao vivo.
↵
Contador de palavras
Texto · Conte palavras, caracteres, frases, parágrafos e tempo de leitura.
↵
Conversor de maiúsculas e minúsculas
Texto · Converta texto para MAIÚSCULAS, minúsculas, Título, camelCase, snake_case e mais.
↵
Ordenador de listas
Texto · Ordene, inverta, embaralhe e remova duplicatas de listas de texto.
↵
Prévia de Markdown
Texto · Escreva em Markdown e veja a prévia renderizada ao vivo, lado a lado.
↵
Calculadora de porcentagem
Números · Calcule porcentagens, aumentos, reduções e quantos % um número é de outro.
↵
Conversor de cores
Cores · Converta cores entre HEX, RGB, HSL e HSV na hora.
↵
Snake
Arcade · Coma, cresça e não bata nas paredes. Um clássico atemporal.
↵
2048
Quebra-cabeça · Deslize e combine as peças até chegar à lendária peça 2048.
↵
Word Grid
Quebra-cabeça · Adivinhe a palavra oculta de cinco letras em seis tentativas com pistas de cores.
↵
Sudoku
Quebra-cabeça · Preencha a grade 9x9 com lógica. Quatro níveis, do fácil ao especialista.
↵
Campo Minado
Estratégia · Use as pistas numéricas para limpar o campo minado. Lógica clássica, três níveis.
↵
Breakout
Arcade · Quebre todos os tijolos com raquete e bola. Power-ups, combos e níveis sem fim.
↵
Treino de digitação
Casual · Melhore seu PPM e sua precisão com treinos de 30 segundos a 5 minutos. Descubra suas teclas fracas.
↵
TypeRunner
Arcade · Corrida de digitação multiplayer. Desafie amigos por link, vença o computador ou persiga o seu fantasma.
↵
Typing Blocks
Arcade · Digite cada palavra antes que o bloco de madeira pouse. Se errar, a pilha sobe em direção à linha.
↵
Bubble Shooter
Arcade · Mire, rebata nas paredes e estoure grupos de três ou mais bolhas.
↵
Road Rush
Arcade · Corra contra sete rivais no trânsito e abra caminho no soco.
↵