Estrutura de um JWT

Três segmentos, dois pontos de separação

A serialização compacta é header.payload.signature — cada segmento codificado em Base64url de forma independente, com os pontos como separadores literais. A codificação é deliberadamente sem padding, então um token contém apenas letras, dígitos, hífens e underscores: seguro em URLs, headers e cookies sem precisar de escape. Decodificar os dois primeiros segmentos não é um hack — é o modo pretendido de inspecionar um token; o terceiro segmento é onde a verificação acontece.

Um token real, com uma assinatura calculada sobre ele, decodifica exatamente assim:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzg0OTIiLCJhdWQiOiJhcGkuZXhhbXBsZS5jb20iLCJpYXQiOjE3NjcyMjU2MDAsImV4cCI6MTc2NzMxMjAwMCwianRpIjoiYjBmNmMyZDQtNGU3YS00YzFmLTlhMmItM2Q1ZTdmOWExYzNlIn0.iDPqw4BRxZtM064Y3EH83XLB0cgEjbj5snSXeM846VY

{"alg":"HS256","typ":"JWT"}

{"iss":"https://auth.example.com","sub":"user_8492",
 "aud":"api.example.com","iat":1767225600,
 "exp":1767312000,
 "jti":"b0f6c2d4-4e7a-4c1f-9a2b-3d5e7f9a1c3e"}

O header: o sumário do token

O header é um pequeno objeto JSON — formalmente, o JWS Protected Header. Dois campos fazem quase todo o trabalho: alg nomeia o algoritmo de assinatura, e typ registra o media type, convencionalmente JWT. Um terceiro, kid (key ID), aponta o verificador para a chave certa quando um emissor publica várias. O header é assinado, mas nunca criptografado, e só é confiável depois que a assinatura é verificada — até lá, alg é uma claim, não um fato.

O payload: as claims registradas e o que cada uma promete

O payload é um objeto JSON de claims. Sete são registradas pelo RFC 7519 com significados precisos e interoperáveis; todo o resto é privado ao emissor e à audiência. Os tempos são valores NumericDate — segundos desde a época Unix, não milissegundos —, e as claims de tempo são apenas informativas para o verificador: checá-las é trabalho do verificador, não algo que o formato imponha.

A assinatura: HS256, RS256 e como a verificação funciona

A assinatura é calculada sobre a entrada de assinatura — o header codificado, um ponto, o payload codificado — usando o algoritmo que o header nomeia. HS256 é HMAC-SHA256 com um segredo compartilhado: rápido e simétrico, apropriado apenas quando quem assina e todo verificador formam um único domínio de confiança, porque qualquer um que tenha o segredo pode cunhar tokens. RS256 é RSA: o emissor assina com uma chave privada e qualquer um — incluindo um navegador — pode verificar com a chave pública publicada, e é isso que faz dele o padrão para protocolos federados como OAuth 2.0 e OpenID Connect.

A verificação recalcula a assinatura e compara. Esse é todo o mecanismo — e é por isso que o header alg sozinho decide como a checagem roda. As bibliotecas se endureceram depois dos ataques de confusão de algoritmo do começo dos anos 2010: um token que alega alg none, ou um token RS256 reprocessado como HS256 usando a chave pública como segredo do HMAC, só verifica contra verificadores que não fixam o algoritmo esperado.

HS256: HMAC-SHA256(secret, header + '.' + payload)
       quem assina e quem verifica compartilham o segredo

RS256: RSA-SHA256(private key, header + '.' + payload)
       o emissor assina; qualquer um verifica com a chave pública

Fixe o algoritmo esperado para cada emissor.
Nunca o deduza apenas do cabeçalho do próprio token.
Nunca aceite alg: none.

Assinado, não lacrado: o que a assinatura não faz

A assinatura prova que o token foi emitido por quem detém a chave e que não foi alterado desde então — integridade e autenticidade. Ela não fornece confidencialidade nenhuma: Base64url é uma codificação, e o payload pode ser lido por qualquer um que veja o token, incluindo extensões de navegador, proxies quando os tokens viajam em URLs e coletores de log. Daí as regras permanentes: nunca coloque segredos em um payload de JWT, nunca envie tokens em URLs e trate cada claim decodificada como dado, não como decisão.

Esse último ponto é a armadilha do lado do cliente. Um navegador pode decodificar um token e ler exp ou sub — mas não consegue verificar o token de forma significativa, porque não detém a chave do emissor: com HS256, o segredo nunca deve chegar ao navegador; com RS256, uma checagem no cliente não prova nada sobre o que o portador pode acessar. Clientes podem inspecionar tokens para apresentação — mostrar um nome, avisar sobre expiração —, mas o servidor deve verificar a assinatura e cada claim a cada requisição. Inspecionar não é verificar, e legível não é autorizado.

Inspecionar tokens com segurança — o ciclo prático

Um ciclo disciplinado de inspeção leva segundos: decodifique o header e o payload, cheque exp e nbf contra o relógio, confirme que iss e aud são o que você espera e só então — no servidor — verifique a assinatura com um algoritmo fixado e a chave certa. Tudo, exceto a verificação final, é processamento de texto puro, e é por isso que um decodificador que roda inteiramente no seu navegador é a ferramenta certa: tokens reais são credenciais bearer, e credenciais devem ficar em abas que você controla, não a sites que podem encaminhá-las.

Lembre do que a estrutura não pode dar a você: revogação — listas de bloqueio baseadas em jti precisam ser construídas e checadas no servidor; confidencialidade — use JWE se você precisa de tokens criptografados; e confiança — um token estruturalmente perfeito de um emissor que você nunca configurou não vale nada. A estrutura diz o que foi prometido; só a verificação diz que a promessa segue intacta.