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
- Usuário se autentica — O cliente envia credenciais (usuário + senha) para o servidor de autenticação.
- 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.
- 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. - 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):
| Claim | Nome | Descrição |
|---|---|---|
sub | Subject | Identificador único da entidade (ID do usuário) |
iss | Issuer | Serviço que emitiu o token |
aud | Audience | Destinatário(s) pretendido(s) do token |
exp | Expiration | Timestamp Unix após o qual o token é inválido |
iat | Issued At | Timestamp Unix de quando o token foi criado |
nbf | Not Before | Timestamp Unix antes do qual o token é inválido |
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
| Algoritmo | Tipo | Chave | Usar quando |
|---|---|---|---|
HS256 | Simétrico (HMAC) | Segredo compartilhado | Serviço único; emissor e verificador compartilham o segredo |
RS256 | Assimétrico (RSA) | Par de chave pública/privada | Múltiplos serviços; emissor assina com chave privada, qualquer serviço verifica com chave pública |
ES256 | Assimétrico (ECDSA) | Par de chave pública/privada | Igual ao RS256, com chaves menores e melhor desempenho |
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 token | Refresh token | |
|---|---|---|
| Finalidade | Autoriza acesso à API | Obtém novos access tokens |
| Tempo de vida | Curto: 5–60 minutos | Longo: horas a semanas |
| Enviado com | Cada requisição à API | Apenas endpoint de renovação do token |
| Armazenamento | Memória ou cookie HttpOnly | Cookie HttpOnly seguro |
| Revogável | Não sem infraestrutura adicional | Sim, via banco de dados de 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
| JWT | Sessão server-side | |
|---|---|---|
| Estado | Stateless — sem armazenamento no servidor | Stateful — sessão armazenada no servidor |
| Escalabilidade | Qualquer servidor verifica qualquer token | Requer sticky sessions ou session store compartilhado |
| Revogação | Não pode revogar antes da expiração sem blacklist | Revogação imediata ao deletar a sessão |
| Tamanho | Maior (token em cada requisição) | Pequeno (apenas session ID no cookie) |
| Melhor para | APIs, microsserviços, SSO, apps mobile | Aplicações web que exigem logout imediato |
Erros comuns de segurança com JWT
| Erro | Risco | Correção |
|---|---|---|
| Armazenar PII no payload | Qualquer pessoa pode decodificar o payload | Armazene apenas claims não sensíveis (ID do usuário, papéis) |
| Access tokens de longa duração (horas/dias) | Roubo de token tem longa janela de exposição | Defina exp para 5–60 minutos |
Não validar a claim alg | Ataques de confusão de algoritmo (ex.: troca RS256 → HS256) | Sempre imponha o algoritmo esperado no servidor |
Armazenar JWT no localStorage | Ataques XSS podem roubar o token | Use cookies HttpOnly, Secure, SameSite=Strict |
| Sem plano de revogação de token | Tokens comprometidos permanecem válidos até expirarem | Implemente expiração curta + rotação de refresh token |
Não validar iss e aud | Tokens de outros serviços são aceitos | Sempre valide as claims de emissor e audiência |
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).