O que é JWT? Estrutura, assinatura e uso seguro

Três blocos base64url separados por pontos: um cabeçalho, um payload e uma assinatura. Aprenda o que cada parte prova, o que não prova e os cinco erros que transformam um JWT em uma brecha de segurança.

📂 Fundamentos para desenvolvedores ⏱ Cerca de 11 minutos 📶 Intermediário 🛠️ Combina com: decodificador JWT

O que você vai aprender

  • Ler um JWT e nomear suas três partes
  • Explicar o que a assinatura prova — e o que ela não prova
  • Usar as claims padrão (exp, iss, aud, sub) corretamente
  • Decidir quando um JWT vence uma sessão no servidor (e quando perde)
  • Evitar os cinco erros clássicos de segurança com JWT
Neste guia
  1. O que é um JWT
  2. Anatomia: as três partes
  3. Como funcionam a assinatura e a verificação
  4. As claims padrão
  5. Quando usar um JWT — e quando não usar
  6. Erros comuns
  7. Teste: decodificador JWT
  8. Perguntas frequentes

O que é um JWT

A JSON Web Token (JWT) é uma forma compacta e segura para URLs de passar uma claim assinada entre duas partes. É assim:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlZhbGV2IiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Três blocos, separados por pontos: header.payload.signature. Um servidor cria um depois que você faz login, entrega-o a você, e você o envia de volta a cada requisição — geralmente em um Authorization: Bearer <token> cabeçalho. O servidor verifica a assinatura e confia nas claims dentro dele, sem consultar nada em um banco de dados. Essa propriedade de “sem consulta” é o ponto central — e, como veremos, também a principal fraqueza.

Anatomia: as três partes

Cada parte é JSON codificado em base64url (base64 com +// substituído por -/_ e o preenchimento removido, para sobreviver em uma URL). Decodifique o exemplo acima e você obtém:

// Header — how the token is signed
{ "alg": "HS256", "typ": "JWT" }

// Payload — the claims (statements about the user)
{ "sub": "1234567890", "name": "Valev", "admin": true, "iat": 1516239022 }

// Signature — HMAC-SHA256 over header.payload, with a secret key
ParteConteúdoSecreto?
CabeçalhoAlgoritmo de assinatura (alg) e tipo (typ)Não — legível por qualquer um
PayloadClaims: quem você é, o que pode fazer, quando expiraNão — legível por qualquer um
AssinaturaHash de cabeçalho + payload, com chave secretaSim — só o emissor pode criá-la
O payload é codificado, não criptografado. Qualquer pessoa que obtenha o token pode decodificá-lo e ler todas as claims — seu ID de usuário, seu e-mail, sua flag de admin. Nunca coloque senhas, segredos ou dados pessoais sensíveis em um JWT. Se o payload precisar ser secreto, você precisa de JWE (JWT criptografado), não de um JWT comum.

Como funcionam a assinatura e a verificação

Para criar a assinatura, o emissor pega base64url(header) + "." + base64url(payload) e a assina:

HMAC-SHA256(secret, header + "." + payload)   // HS256: shared secret
RS256: sign with a private key, verify with a public key

A verificação é o mesmo cálculo ao contrário: o servidor recalcula a assinatura sobre o cabeçalho e o payload que recebeu, usando sua própria chave secreta, e compara. Se até um caractere do payload for alterado — digamos, trocar "admin": false para true — a assinatura não corresponde mais e o token é rejeitado.

Duas famílias de algoritmos importam. Simétrico (HS256): um segredo compartilhado assina e verifica — simples, mas qualquer pessoa com o segredo pode falsificar tokens, então só o emissor pode guardá-lo. Assimétrico (RS256/ES256): uma chave privada assina, uma chave pública verifica — o verificador pode ser um serviço diferente, e é assim que funciona a federação no estilo “login com Google”.

As claims padrão

ClaimSignificadoPor que importa
issEmissor — quem criou o tokenRejeitar tokens de estranhos
subSubject — de quem é este token (ID de usuário)A identidade com a qual o aplicativo age
audAudience — para qual serviço o token éImpede que um token de um aplicativo seja reutilizado em outro
expExpiração — tempo Unix após o qual é inválidoLimita o dano de um token roubado
iatEmitido emDetectar tokens criados antes de uma mudança de senha
nbfNão antes deTokens que só se tornam válidos depois

Além destas, os aplicativos adicionam suas próprias claims — papéis, permissões, um nome de exibição. Mantenha o payload pequeno: o token é enviado a cada requisição, então um token de 5 KB é um imposto sobre cada chamada.

Quando usar um JWT — e quando não usar

Os JWTs brilham quando a verificação precisa acontecer sem uma ida e volta ao banco de dados, ou entre serviços que não compartilham um armazenamento de sessão: APIs, microsserviços e single sign-on. O verificador só precisa da chave.

Eles perdem em um ponto importante: você não pode revogar um facilmente. Uma sessão no servidor pode ser excluída no momento em que um usuário sai ou muda a senha; um JWT continua válido até expirar, porque não há nada a excluir. As mitigações padrão são tempos de expiração curtos (minutos, não dias) mais refresh tokens — um token de longa duração que só é enviado ao endpoint de login para gerar novos JWTs de curta duração — ou uma lista de revogação, que reintroduz silenciosamente a consulta ao banco de dados que o JWT deveria evitar.

Regra prática: se você tem um aplicativo e um banco de dados, um cookie de sessão clássico é mais simples e seguro. Use JWT quando tiver muitos serviços ou quando o token precisar cruzar uma fronteira de confiança.

Erros comuns

  • Confiar em um token decodificado pelo cliente. Decodificar não prova nada — só a verificação da assinatura prova. O admin: true em um payload decodificado é uma claim, não um fato, até que a assinatura seja verificada.
  • Aceitar alg: none. Um token não assinado deve ser rejeitado. Bibliotecas que ainda o aceitam são a vulnerabilidade de JWT mais antiga que existe — e ela ainda aparece.
  • Segredos fracos ou vazados. HS256 com o segredo secret HS256 com o segredo
  • Sem expiração (exp). Um token roubado então funciona para sempre. Defina um curto exp e use refresh tokens.
  • Colocar segredos no payload. Base64url não é criptografia — qualquer um pode lê-lo. Veja o destaque acima.
  • Armazenar tokens no localStorage. Qualquer brecha de cross-site scripting (XSS) permite que um invasor o leia. Cookies HttpOnly são o lugar mais seguro para tokens de navegador.

Teste: decodificador JWT

Cole um token no decodificador JWT e veja-o se dividir em cabeçalho, payload e datas legíveis — a maneira mais rápida de ver a estrutura que este guia descreve.

Abrir o decodificador JWT →

Continue aprendendo

Perguntas frequentes

Um JWT é criptografado?

Não. Um JWT padrão (JWS) é assinado, não criptografado — o payload é base64url, que qualquer um pode decodificar. A criptografia é um formato separado, JWE, usado quando o conteúdo em si precisa permanecer secreto.

Como revogo um JWT quando um usuário sai?

Você não pode excluí-lo diretamente — ele continua válido até o exp. As respostas práticas são expiração curta com refresh tokens, ou uma denylist no servidor com os IDs dos tokens revogados (a claim jti) verificada em endpoints sensíveis.

JWT vs cookie de sessão — qual devo escolher?

Um cookie de sessão para um único aplicativo com banco de dados: mais simples, revogável instantaneamente. Um JWT para APIs e microsserviços onde os verificadores não podem compartilhar um armazenamento de sessão, ou onde os tokens cruzam fronteiras de serviço. Muitos sistemas usam os dois: uma sessão para o navegador, JWTs para chamadas de serviço para serviço.

Onde devo armazenar um JWT no navegador?

Em um cookie HttpOnly, Secure, SameSite — o JavaScript não consegue lê-lo, então o XSS não pode roubá-lo. O localStorage é conveniente, mas legível por qualquer script na página, incluindo um injetado.

Posso decodificar um JWT sem o segredo?

Sim — decodificar o cabeçalho e o payload não precisa de nenhuma chave; só verificar a assinatura precisa. É por isso que a ferramenta decodificador JWT pode mostrar o conteúdo de um token instantaneamente, e por isso você nunca deve colocar segredos no payload.