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.payloadcom 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 comohttps://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 cujoaudnã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 deheader.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 pelokid.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.