Como decodificar um JWT (e por que decodificar nao e verificar)

Voce esta depurando um fluxo de autenticacao e alguem te entrega uma longa sequencia de caracteres incompreensiveis: eyJhbGciOi.... Isso e um JSON Web Token, ou JWT, e dentro dele ha dados estruturados que voce consegue ler em segundos assim que souber como. Este guia explica do que e feito um JWT, como decodifica-lo para inspecionar suas claims e o unico ponto de seguranca que confunde os desenvolvedores constantemente: decodificar um token nao e a mesma coisa que verifica-lo. Voce pode acompanhar usando o Decodificador de JWT gratuito.

Do que e feito um JWT

Um JWT e uma forma compacta de transportar informacoes assinadas entre duas partes, na maioria das vezes para provar quem e um usuario depois que ele faz login. Olhando de perto, voce vera que ele esta dividido em tres partes separadas por pontos:

header.payload.signature

Cada uma das duas primeiras partes e um objeto JSON codificado em Base64url, e por isso parece uma serie de caracteres aleatorios em vez de texto legivel. As tres pecas sao:

• Header (cabecalho). Um pequeno JSON que descreve o token, principalmente o algoritmo de assinatura (como HS256 ou RS256) e o tipo do token.
• Payload (carga util). A parte interessante. Ela guarda as claims: quem e o usuario, quando o token foi emitido, quando ele expira e quaisquer dados personalizados que o emissor adicionou.
• Signature (assinatura). Um carimbo criptografico criado a partir do cabecalho, da carga util e de uma chave secreta. E o que permite a um servidor confirmar que o token nao foi adulterado.

Os pontos sao separadores literais, entao um JWT e sempre composto por tres blocos Base64url unidos por pontos.

Como decodificar e ler as claims

Decodificar simplesmente reverte a codificacao Base64url do cabecalho e da carga util para que voce consiga ler o JSON dentro deles. O Decodificador de JWT gratuito faz isso instantaneamente e, o mais importante, roda inteiramente no seu navegador, de modo que o token que voce cola nunca e enviado a lugar nenhum.

1. Copie o token completo, as tres partes incluindo os pontos.
2. Cole-o no Decodificador de JWT.
3. Leia o cabecalho e a carga util decodificados como JSON formatado.

Na carga util voce vera com frequencia claims padrao: sub para o sujeito (geralmente um id de usuario), iat para o horario de emissao, exp para a expiracao e iss para o emissor. Os valores de tempo costumam ser timestamps Unix. Le-los e a forma mais rapida de responder perguntas como ‘este token expirou?’ ou ‘para qual usuario ele e?’ durante a depuracao.

Decodificar nao e verificar

Aqui esta o ponto que vale a pena gravar na memoria. Qualquer pessoa que tenha o token pode decodificar o cabecalho e a carga util, sem chave e sem senha. A codificacao e reversivel por design, exatamente como o Base64. Decodificar diz o que o token afirma, mas nao diz nada sobre se essas afirmacoes sao confiaveis.

Verificar e uma etapa separada e criptografica. Um servidor recalcula a assinatura usando a chave secreta ou publica e verifica se ela corresponde a assinatura presente no token. Somente uma assinatura valida prova que o token foi emitido por quem ele diz e que nao foi alterado. Um decodificador nao pode fazer isso por voce, porque ele nao tem a chave. Portanto, nunca decida que ‘este usuario esta autenticado’ apenas com base em uma decodificacao, essa verificacao precisa acontecer no servidor com a chave adequada.

Nunca coloque segredos na carga util

Como a carga util e trivialmente legivel por qualquer um que tenha o token, ela e o lugar errado para qualquer coisa sensivel. Nao coloque senhas, chaves de API ou dados pessoais privados na carga util de um JWT, ja que ela e efetivamente publica para quem interceptar ou receber o token. A assinatura impede a adulteracao, nao a leitura. Trate a carga util como visivel por padrao e mantenha os segredos no lado do servidor.

Ferramentas relacionadas para inspecionar tokens

Decodificar um JWT costuma levar a algumas tarefas vizinhas. Se voce quer entender a propria camada Base64url, a ferramenta de codificar e decodificar Base64 permite experimentar com a mesma codificacao que o token usa. Depois que voce tiver uma carga util decodificada, o Formatador de JSON vai indenta-la e organiza-la para que um conjunto de claims profundamente aninhado fique facil de examinar. E se voce esta raciocinando sobre como a assinatura e construida, o Gerador de Hash e uma boa forma de ver como o hashing unidirecional se comporta, ja que a assinatura se apoia em primitivas criptograficas relacionadas.

A versao curta

Um JWT e composto por tres partes codificadas em Base64url, cabecalho, carga util e assinatura, unidas por pontos. Decodificar reverte a codificacao para que voce possa ler as claims, o que e perfeito para depuracao. Apenas lembre que decodificar nao e verificar: a carga util e legivel por qualquer um, entao nunca armazene segredos nela, e sempre verifique a assinatura no servidor antes de confiar em um token. Quando voce precisar inspecionar um rapidamente e com privacidade, o Decodificador de JWT gratuito o le diretamente no seu navegador.