O que é JWT (JSON Web Token)? | Autenticação Stateless Explicada

JWT é um padrão aberto para transmitir claims entre partes como um objeto JSON compacto e assinado — a base da autenticação stateless em APIs, microsserviços e sistemas de single sign-on.

Resumo JWT (JSON Web Token) é um padrão aberto (RFC 7519) que codifica claims — afirmações sobre um usuário ou entidade — em uma string compacta e URL-safe que pode ser assinada criptograficamente e verificada. Um JWT tem três partes: header, payload e signature. Quando um usuário se autentica, o servidor emite um JWT que o cliente envia com cada requisição subsequente. O servidor verifica a assinatura sem consultar um banco de dados, viabilizando a autenticação stateless. Access tokens JWT devem expirar em 5–60 minutos. Refresh tokens cuidam das sessões de longa duração.

O que é JWT?

JWT (JSON Web Token) é um padrão aberto (RFC 7519) para transmitir informações com segurança entre partes como um objeto JSON compacto e URL-safe. Um JWT codifica claims — afirmações sobre uma entidade (tipicamente um usuário) — e é assinado criptograficamente para que o receptor possa verificar sua autenticidade e integridade sem contatar o emissor.

JWT resolve um problema específico: como passar informações de identidade verificadas entre serviços em um sistema stateless sem armazenar dados de sessão no servidor.

Como o JWT funciona

1. Usuário se autentica — O cliente envia credenciais (usuário + senha) para o servidor de autenticação.
2. Servidor emite o JWT — O servidor valida as credenciais, cria um JWT com as claims do usuário (ID do usuário, papéis, expiração), assina com um segredo ou chave privada e o retorna.
3. Cliente armazena e envia o JWT — O cliente armazena o JWT (tipicamente em um cookie HttpOnly ou em memória) e o envia no header Authorization: Bearer <token> com cada requisição.
4. Servidor verifica o JWT — O servidor verifica a assinatura, valida a expiração e as claims, e processa a requisição — sem necessidade de consulta ao banco de dados.

Esse fluxo é stateless: o servidor não mantém dados de sessão. Qualquer instância de servidor que conhece a chave de assinatura pode verificar o token.

Estrutura do JWT: três partes

Um JWT é formado por três segmentos codificados em Base64URL separados por pontos: header.payload.signature

Header

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

Especifica o algoritmo de assinatura (HS256, RS256, ES256) e o tipo do token. Codificado em Base64URL.

Payload

{
  "sub": "user_123",
  "name": "Maria Silva",
  "role": "admin",
  "iat": 1712345678,
  "exp": 1712349278
}

Contém as claims. Claims registradas (definidas pela RFC 7519):

Os payloads JWT são codificados em Base64URL, não criptografados. Qualquer pessoa que interceptar um JWT pode decodificar e ler o payload. Nunca armazene senhas, números de cartão de crédito ou dados pessoais (PII) nas claims JWT.

Signature

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

A assinatura garante que o token não foi adulterado. O servidor a verifica usando o mesmo segredo (HMAC) ou a chave pública do emissor (RSA/ECDSA).

Algoritmos de assinatura: HMAC vs RSA

Use HS256 para autenticação simples em serviço único. Use RS256 ou ES256 quando múltiplos serviços independentes precisam verificar tokens sem acesso ao segredo de assinatura.

Access tokens vs refresh tokens

Access tokens de curta duração limitam o dano em caso de roubo do token. Refresh tokens viabilizam sessões longas sem exigir que o usuário se autentique novamente.

JWT vs sessões server-side

Erros comuns de segurança com JWT

Quando usar JWT

Use JWT quando precisar de:

• Autenticação stateless para APIs REST ou GraphQL
• Single Sign-On (SSO) entre múltiplas aplicações ou domínios
• Claims de autorização embutidas no token (papéis, escopos, permissões)
• Apps mobile ou SPAs que não podem manter sessões server-side
• Autenticação serviço a serviço em microsserviços

Não use JWT quando precisar de:

• Revogação imediata de sessão (ex.: logout deve bloquear todas as requisições instantaneamente)
• Log server-side de cada ação do usuário com contexto de sessão
• Tokens maiores que ~8KB (a sobrecarga de banda cresce a cada requisição)

Perguntas frequentes

O que é JWT em termos simples? JWT é um token que prova quem você é e o que você tem permissão de fazer. O servidor o cria, assina criptograficamente e entrega a você. Você o envia com cada requisição. O servidor verifica a assinatura sem precisar consultá-lo em um banco de dados.

JWT é seguro? JWT é seguro quando usado corretamente. A assinatura previne adulteração. Porém, o payload é apenas codificado em Base64 — não criptografado — portanto qualquer pessoa que obtiver o token pode ler seu conteúdo. Use HTTPS para toda transmissão de tokens e nunca coloque dados sensíveis no payload.

Qual é a diferença entre JWT e OAuth? OAuth 2.0 é um framework de autorização que define como tokens são emitidos e usados. JWT é um formato de token. OAuth 2.0 comumente usa JWT como formato de access token, mas JWT pode ser usado independentemente do OAuth.

Como invalidar um JWT antes de ele expirar? JWTs não podem ser invalidados sem infraestrutura adicional. Opções: (1) use tempos de expiração curtos (5–15 minutos), (2) mantenha uma blacklist de tokens em um cache (Redis), (3) use uma claim de versão no payload que se torna inválida quando o usuário muda a senha ou faz logout.

Qual é a diferença entre HS256 e RS256? HS256 usa um segredo compartilhado único — tanto o emissor quanto qualquer verificador precisam conhecê-lo. RS256 usa um par de chaves pública/privada — o emissor assina com a chave privada, e qualquer verificador pode confirmar com a chave pública sem acesso ao segredo. Use RS256 quando múltiplos serviços independentes precisam verificar tokens.

Devo armazenar o JWT no localStorage ou em cookies? Armazene o JWT em cookies HttpOnly, Secure, SameSite=Strict. O localStorage é acessível via JavaScript e vulnerável a ataques XSS. Cookies HttpOnly impedem completamente o acesso via JavaScript. Cookies requerem proteção contra CSRF, mas esse é um trade-off gerenciável.

O que acontece quando um JWT expira? Quando a claim exp de um JWT está no passado, o servidor o rejeita com uma resposta 401 Unauthorized. O cliente deve usar um refresh token para obter um novo access token, ou solicitar que o usuário se autentique novamente.

O que é uma claim JWT? Uma claim é uma afirmação sobre o sujeito do token. Por exemplo, "sub": "user_123" afirma que o sujeito do token é o usuário 123. "role": "admin" afirma que esse usuário é administrador. As claims são definidas pela RFC 7519 (claims registradas) ou pela aplicação (claims privadas).