JWT explicado: estrutura, claims e como decodificar um

Se você já trabalhou com uma API web moderna, encontrou os JWTs — aquelas longas cadeias de embaralhado com dois pontos que aparecem em respostas de login e cabeçalhos Authorization. Parecem opacos, mas são surpreendentemente legíveis quando você conhece a estrutura. Este guia explica o que é um JSON Web Token, o que há dentro dele, como a assinatura funciona e os erros de segurança a evitar.

Para que serve um JWT

Um JSON Web Token (JWT) é uma forma compacta e autocontida de carregar um conjunto de claims — afirmações como "este é o usuário 42 e ele entrou às 10:05". Seu uso principal é autenticação: depois do login, um servidor emite um JWT, seu app o envia de volta a cada requisição, e o servidor confia nele em vez de procurar você num armazenamento de sessão toda vez. Como o token carrega a informação em si, ele é chamado de sem estado (stateless).

As três partes

Todo JWT são três seções codificadas em Base64URL unidas por pontos: header.payload.signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3x9kQ...
└──── header ────┘ └── payload ──┘ └ signature ┘

1. Cabeçalho (Header)

Metadados sobre o token — o algoritmo de assinatura (alg, ex. HS256) e o tipo (typ: JWT). Decodificado, é só um pequeno JSON:

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

2. Carga (Payload)

Os claims — os dados de verdade. Alguns nomes são padronizados (chamados claims registrados):

• sub — sujeito (subject), geralmente o ID do usuário.
• iss — emissor (issuer), quem criou o token.
• aud — audiência (audience), para quem é.
• exp — hora de expiração (um timestamp Unix).
• iat — hora de emissão (um timestamp Unix).

Esses valores exp e iat são segundos desde 1970 — se você precisa lê-los como datas reais, um conversor de timestamp os transforma em horas legíveis.

3. Assinatura (Signature)

A assinatura é o que torna o token confiável. O emissor pega o cabeçalho e a carga e, usando uma chave secreta, produz uma assinatura criptográfica. Qualquer um com a chave pode verificar que o cabeçalho e a carga não foram alterados — mude um único caractere na carga e a assinatura já não bate.

A coisa mais importante de entender

Um JWT é assinado, não criptografado. O cabeçalho e a carga estão apenas codificados em Base64URL, o que significa que qualquer um pode decodificá-los e lê-los — sem chave. A assinatura impede a adulteração, não a leitura.

A consequência prática: nunca ponha segredos na carga de um JWT. Nada de senhas, números de cartão ou dados privados — assuma que a carga é pública. Você pode confirmar isso colando qualquer token no nosso decodificador de JWT, que lê o cabeçalho e os claims na hora, inteiramente no seu navegador (o token nunca sai do seu dispositivo). Por baixo é só decodificação Base64 — o decodificador só te poupa os passos.

Verificar vs. decodificar

São duas ações diferentes, e confundi-las é um bug de segurança real. Decodificar lê a carga — qualquer um pode fazer e não prova nada. Verificar checa a assinatura com a chave e confirma que o token é genuíno e inalterado. Um servidor deve verificar cada token antes de confiar nele; decodificar sozinho não é autenticação.

Armadilhas comuns

• Confiar num token não verificado — sempre cheque a assinatura no servidor antes de agir com base nos claims.
• Ignorar a expiração — respeite exp; um token expirado deve ser rejeitado.
• Guardar dados sensíveis na carga — ela é legível por qualquer um.
• A armadilha `alg: none` — algumas bibliotecas já aceitaram tokens que alegavam "sem assinatura". Rejeite-os e fixe o algoritmo esperado.

Entenda isso e os JWTs deixam de ser cadeias intimidadoras e viram um formato simples e transparente: claims legíveis, protegidos por uma assinatura que você deve verificar antes de confiar.