O que é JWT? Estrutura, claims e decodificação

O que é JWT

O que é JWT? Estrutura, claims e um decodificador privado | We.Inc

JSON Web Tokens explicados: header, payload e assinatura, as sete claims registradas da RFC 7519, armadilhas de segurança e um decodificador que nunca envia seu token para lugar nenhum.

Um JWT (JSON Web Token) é uma string compacta e segura para URLs, com três partes em base64url separadas por pontos: um header que indica o algoritmo, um payload de claims como sub e exp, e uma assinatura. Qualquer pessoa pode decodificar e ler o payload; só a assinatura, verificada com a chave certa, prova que ninguém o alterou.

Nomes de claims registradas (RFC 7519, seção 4.1)

Claim
Nome
Significado

Emissor
Quem emitiu o token

Assunto
A quem o token se refere, geralmente um id de usuário

Público
Quais destinatários devem aceitá-lo

Data de expiração
Rejeitar a partir deste momento

Não antes de
Rejeitar antes deste momento

Emitido em
Quando o token foi criado

ID do JWT
Um id único, útil para impedir reuso

Cole um token no decodificador abaixo para ver o header e o payload, com cada claim registrada explicada e cada timestamp convertido em uma data legível. A decodificação acontece no próprio JavaScript desta página, então o token nunca é enviado. Isso importa, porque um token válido é uma chave para a conta de alguém.

O decodificador divide o token nos pontos e espera três partes (um JWE com cinco partes é criptografado e não pode ser lido).
Ele converte as duas primeiras partes de base64url de volta para texto e as interpreta como JSON.
As claims registradas ganham um rótulo, e exp, nbf e iat aparecem como datas, indicando se o token está válido agora.
A assinatura é mostrada, mas não verificada: isso exige a chave do emissor, que fica no seu servidor.

Nunca coloque segredos ou dados pessoais em um payload. Assinar impede edições; não esconde nada.
Fixe os algoritmos que o seu servidor aceita. Nunca deixe o header alg do próprio token decidir, e rejeite none.
Sempre confira exp, iss e aud, não só a assinatura, para que um token feito para outro serviço seja recusado.
Chaves HS256 devem ser bytes aleatórios longos. A RFC 8725 diz que senhas fáceis de memorizar não devem ser usadas diretamente.
Mantenha os access tokens com vida curta e renove-os, porque um JWT roubado continua válido até expirar.

Perguntas frequentes

É seguro decodificar um JWT online?

Só se a decodificação acontecer no seu navegador. O token é uma credencial: quem tiver um válido pode chamar a API como aquele usuário até ele expirar. O decodificador desta página roda localmente e não envia nada, mas, para tokens de produção, o hábito mais seguro é decodificar apenas tokens de teste.

Um JWT é criptografado?

Um JWT assinado comum (um JWS) não é. O payload dele é apenas codificado em base64url, o que qualquer pessoa pode reverter. Tokens criptografados existem como JWE, com cinco partes separadas por pontos em vez de três, mas a maioria dos tokens de login e de API é assinada, não criptografada.

Em que formato ficam exp e iat?

NumericDate: segundos inteiros desde 1970-01-01T00:00:00Z, ignorando segundos bissextos. O Date.now() do JavaScript retorna milissegundos, então divida por 1000 antes de comparar, um bug muito comum.

Devo guardar um JWT no localStorage ou em um cookie?

Qualquer script rodando na página pode ler o localStorage, então um único bug de cross-site scripting pode roubar o token. Um cookie HttpOnly, Secure e SameSite o mantém longe dos scripts, ao custo de lidar com CSRF. Muitos times escolhem o cookie para sessões no navegador.

Consigo deslogar um usuário com um JWT?

Não só com ele, porque o token continua válido até o exp. Use expiração curta mais refresh tokens que você possa revogar, ou mantenha uma lista de bloqueio de valores jti para tokens que precisam morrer antes.

As três partes

O header é um pequeno objeto JSON como {"alg":"HS256","typ":"JWT"}. O payload guarda as claims. Cada um é codificado em base64url, que é base64 com - e _ no lugar de + e / e sem preenchimento =, então o resultado é seguro em URLs e headers.
A assinatura é calculada sobre as duas primeiras partes codificadas, unidas por um ponto. Mude um caractere do payload e a assinatura deixa de bater.

Algoritmos de assinatura

O HS256 usa um único segredo compartilhado para assinar e verificar, então todo serviço que confere tokens também pode emiti-los. RS256 e ES256 assinam com uma chave privada e verificam com uma chave pública, o que serve para cenários em que muitos serviços verificam, mas só um emite.

Armadilhas que ainda causam vazamentos

Tokens sem proteção com alg none não têm assinatura nenhuma. Uma biblioteca que confia no header pode ser enganada para aceitar um deles, ou para tratar uma chave RSA pública como um segredo HMAC. A RFC 8725 diz às bibliotecas que deixem quem as chama fixar os algoritmos permitidos, e você deve fazer isso.

Decodificar e verificar no código

Decodificar um payload em JavaScript puro

Lê as claims sem verificá-las. Serve para mostrar um nome de usuário na UI, nunca para decidir acesso.

Verificar no servidor com jose

O jwtVerify confere a assinatura, exp e nbf, e com estas opções também o emissor, o público e o algoritmo permitido.

Decodificador de JWT privado

Cole um token para ler o header e o payload. A decodificação roda no seu navegador; o token não é enviado, guardado nem registrado.

Quem emitiu o token

A quem o token se refere, geralmente um id de usuário

Quais destinatários devem aceitá-lo

Rejeitar a partir deste momento

Rejeitar antes deste momento

Quando o token foi criado

Um id único, útil para impedir reuso

JWT

Carregar token de exemplo

Limpar

Header

Payload

Assinatura (não verificada aqui)

Claims explicadas

Claim

Valor

Significado

Claim personalizada

Um JWT assinado tem 3 partes separadas por pontos; este tem {n}.

5 partes indicam um JWE criptografado, que não pode ser lido sem a chave.

A parte {n} não é JSON válido em base64url.

Expirou {v}

Válido até {v}

Não válido até {v}

alg é none: este token não tem assinatura e deve ser rejeitado.

Decodificado localmente. Nada sai desta página.

Comece grátis · Sem cartão de crédito