Autenticação JWT: guia completo de implementação segura

Se você já tentou implementar autenticação JWT, sabe que o básico parece simples: gerar um token, enviar para o cliente, validar nas requisições. O problema é que os detalhes, como armazenar a chave secreta, escolher o algoritmo certo ou lidar com expiração, são onde a maioria das implementações quebra. Este guia cobre o passo a passo completo, com os erros que eu já vi (e cometi) para você não repetir.

Pré-requisitos

Antes de começar, você precisa de um servidor HTTP (Node.js com Express, ASP.NET Core, ou similar), uma rota de login que receba credenciais, e acesso ao pacote/certificação JWT da sua linguagem (jsonwebtoken no Node, System.IdentityModel.Tokens.Jwt no .NET). Ter um banco de usuários com senhas hashadas (bcrypt, Argon2) é obrigatório.

Passo 1: Gere o token com o payload mínimo

No momento do login, após validar a senha, crie o token JWT. O payload deve conter apenas o essencial: o identificador do usuário (sub), a data de emissão (iat) e a data de expiração (exp). Nunca coloque senhas, roles completas ou dados sensíveis, o token não é criptografado, apenas assinado. Exemplo em Node.js:

const token = jwt.sign({ sub: user.id, iat: Math.floor(Date.now() / 1000) }, SECRET_KEY, { expiresIn: '15m' });

Erro comum: usar expiresIn muito longo (dias ou semanas). Um token de acesso deve expirar em minutos (15 a 60). Para sessões longas, use refresh tokens.

Passo 2: Armazene a chave secreta com segurança

A chave secreta (ou par de chaves RSA/ECDSA) é o que impede qualquer um de forjar tokens. Nunca coloque ela no código-fonte. Use variáveis de ambiente, um cofre de chaves (como AWS Secrets Manager ou HashiCorp Vault), ou um arquivo .env fora do repositório. A chave deve ter pelo menos 256 bits (32 caracteres aleatórios).

Erro comum: gerar a chave uma vez e nunca rotacioná-la. Programe uma rotação periódica (a cada 6 meses) e mantenha a chave anterior válida por um período de transição.

Passo 3: Envie o token no cabeçalho Authorization

O cliente deve enviar o token em toda requisição protegida, no cabeçalho HTTP Authorization com o formato Bearer <token>. Exemplo:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Erro comum: enviar o token na URL (query string) ou no corpo da requisição. Isso expõe o token em logs de servidor e histórico do navegador. Sempre use o cabeçalho padrão.

Passo 4: Valide o token em cada requisição

Crie um middleware que:

1. Extraia o token do cabeçalho Authorization.
2. Verifique a assinatura com a chave secreta.
3. Confira se o token não expirou (campo exp).
4. Verifique se o emissor (iss) e a audiência (aud) são os esperados, se você usou esses campos.

Se alguma validação falhar, retorne HTTP 401 com uma mensagem genérica ("Token inválido" ou "Token expirado").

Erro comum: ignorar a validação do exp ou confiar apenas no cliente. Sempre valide no servidor.

Passo 5: Implemente refresh tokens para sessões longas

Um token de acesso com vida curta (15 minutos) força o cliente a fazer login novamente. Para evitar isso, use um refresh token: um token opaco (não JWT) armazenado em banco, com validade de dias ou semanas, que permite obter novos tokens de acesso sem reautenticação.

Erro comum: fazer o refresh token ser um JWT também. Prefira um hash aleatório armazenado no banco, que pode ser revogado individualmente.

Passo 6: Proteja contra ataques comuns

• HTTPS obrigatório: sem HTTPS, o token é capturado em texto claro.
• Armazenamento no cliente: evite localStorage (vulnerável a XSS). Prefira cookies HttpOnly e Secure para tokens de acesso, ou armazene em memória (variável JS) e reobtenha via refresh.
• Revogação: tokens JWT são stateless, não podem ser revogados individualmente. Se precisar revogar, mantenha uma blacklist em cache (Redis) ou reduza a validade do token.
• Algoritmo: use HS256 (HMAC com SHA-256) para chave secreta simétrica, ou RS256 (RSA) para assimétrica. Nunca use none como algoritmo.

Erro comum: não validar o algoritmo recebido no token. Um atacante pode alterar o cabeçalho para alg: none e forjar tokens. Sempre force o algoritmo esperado.

Checklist do que você implementou

• [ ] Geração de token com payload mínimo (sub, iat, exp)
• [ ] Chave secreta armazenada em variável de ambiente
• [ ] Token enviado no cabeçalho Authorization (Bearer)
• [ ] Middleware de validação com checagem de assinatura e expiração
• [ ] Refresh token armazenado em banco (se aplicável)
• [ ] HTTPS configurado no servidor
• [ ] Algoritmo fixo (HS256 ou RS256)
• [ ] Armazenamento seguro no cliente (cookie HttpOnly ou memória)

Perguntas frequentes sobre autenticação JWT

Qual a diferença entre JWT e sessão tradicional?

Sessão tradicional armazena o estado no servidor (memória ou banco), exigindo consulta a cada requisição. JWT é stateless: o token carrega os dados necessários e é validado apenas pela assinatura. Isso escala melhor, mas dificulta revogação individual.

JWT é seguro?

Sim, desde que implementado corretamente: use HTTPS, chave secreta forte, token de curta duração, algoritmo fixo e armazenamento seguro no cliente. O principal risco é o roubo do token, mitigado com HTTPS e refresh tokens.

Preciso usar refresh token?

Depende. Se sua aplicação precisa de sessões longas (dias), sim. Se o usuário faz login a cada uso (bancos, por exemplo), tokens de curta duração sem refresh são suficientes.

Como revogar um JWT antes da expiração?

JWT puro não permite revogação. Soluções: manter uma blacklist em cache (Redis) verificada no middleware, ou usar tokens de curta duração combinados com refresh tokens que podem ser revogados no banco.

Qual algoritmo de assinatura devo usar?

Para a maioria dos casos, HS256 (HMAC com SHA-256) com chave secreta é suficiente e rápido. Se precisar de múltiplos serviços que não compartilham a chave, use RS256 (RSA) com par de chaves pública/privada.

O que fazer se o token vazar?

Com JWT stateless, não há como invalidar o token vazado até sua expiração. Reduza o tempo de expiração (5-15 minutos), force logout de todos os dispositivos (mude a chave secreta, invalidando todos os tokens) e implemente refresh tokens revogáveis.