Login JWT em Node.js: aprenda a proteger APIs de forma simples

Por que usar JWT para autenticação?

O que é JWT? Entendendo a anatomia do token

• Header (cabeçalho): a primeira parte do JWT é um header JSON, normalmente contendo dois campos: o tipo do token (que é JWT) e o algoritmo de criptografia usado para assinar o token (por exemplo, HS256 para HMAC SHA-256, RS256 para RSA). Esse header é Base64URL codificado e forma a primeira seção do token. O Header define o que é o token e como ele foi assinado.

• Payload (carga): a segunda parte é o payload, também um objeto JSON, que carrega os claims – isto é, os dados que queremos transmitir ou validar. Aqui podem estar informações como o ID do usuário, nome, e até mesmo permissões ou papel (ex: role: "admin"). Existem claims registrados padronizados (como iss emissor, sub sujeito, exp expiração, aud audiência etc.), mas você pode incluir campos personalizados conforme a necessidade da sua aplicação. O payload também é codificado em Base64URL e compõe a segunda parte do JWT. Importante: não coloque informações sensíveis demais no payload, pois embora seja codificado, não é criptografado – qualquer um com o token pode decodificar essa parte e ler seu conteúdo.

• Signature (assinatura): por fim, temos a assinatura digital do token. Para criá-la, o emissor do token (geralmente o seu servidor de autenticação) pega o header e o payload codificados, junta com uma chave secreta (no caso de algoritmos simétricos) ou chave privada (no caso de assimétricos) e aplica o algoritmo especificado (como SHA-256). O resultado é uma assinatura, que é anexada ao final do token. Essa signature permite que qualquer parte que receba o JWT verifique a autenticidade do token – ou seja, confirme que foi gerado por quem diz que gerou e que seu conteúdo (header/payload) não foi alterado no caminho. Se alguém tentar modificar o payload (por exemplo, se passando por outro usuário), a assinatura não irá mais bater na verificação com a chave secreta e o token será rejeitado. Segurança na prática!

Implementando login com JWT em Node.js e Fastify

mkdir jwt-fastify-api && cd jwt-fastify-api
npm init -y

npm install fastify @fastify/jwt dotenv

// index.js
const fastify = require('fastify')({ logger: true });
require('dotenv').config();

// Registrando o plugin JWT com uma chave secreta
fastify.register(require('@fastify/jwt'), {
  secret: process.env.JWT_SECRET || 'supersecret'  // use variável de ambiente em produção!
});

// Dados de exemplo - em uma aplicação real, use um banco de dados
const users = [
  { id: 1, name: 'Mayk', email: 'mayk@example.com', password: '123456', role: 'admin' },
  { id: 2, name: 'Diego', email: 'diego@example.com', password: 'abcdef', role: 'user' }
];
// Use hashes criptográficos (bcrypt) para senhas em exemplos reais.

// Rota de login
fastify.post('/login', async (request, reply) => {
  const { email, password } = request.body;

  // Verifica se existe um usuário com as credenciais fornecidas
  const user = users.find(u => u.email === email);
  if (!user || user.password !== password) {
    return reply.code(401).send({ error: 'Credenciais inválidas' });
  }

  // Monta o payload do token JWT (informações que vamos codificar no token)
  const tokenPayload = {
    id: user.id,
    name: user.name,
    role: user.role
  };

  // Gera o token JWT assinado com nossa chave secreta
  const token = fastify.jwt.sign(tokenPayload, { expiresIn: '1h' });

  return reply.send({ 
    token,
    message: `Bem-vindo, ${user.name}!`,
  });
});

// Middleware de autenticação (hook onRequest) para rotas protegidas
fastify.decorate("authenticate", async function(request, reply) {
  try {
    await request.jwtVerify(); // verifica o token JWT presente no header Authorization
  } catch (err) {
    reply.code(401).send({ error: 'Token inválido ou ausente' });
  }
});

// Rota de perfil do usuário logado (protegida)
fastify.get('/profile', { onRequest: [fastify.authenticate] }, async (request, reply) => {
  // Se chegou aqui, request.user contém os dados do token decodificado
  const userData = request.user;
  return reply.send({ profile: userData });
});

// Rota de admin (protegida e com verificação extra de autorização)
fastify.get('/admin', { onRequest: [fastify.authenticate] }, async (request, reply) => {
  const user = request.user;
  if (user.role !== 'admin') {
    return reply.code(403).send({ error: 'Acesso negado: você não é admin.' });
  }
  // ... lógica para retornar dados administrativos
  return reply.send({ secretInfo: 'Só admins veem isso aqui 😎' });
});

// Inicia o servidor na porta 3000
fastify.listen({ port: 3000 }, err => {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log('Servidor rodando em http://localhost:3000 🚀');
});

Segurança e arquitetura com JWT

• Segredo seguro e em variável de ambiente: Já enfatizamos, mas não custa repetir: mantenha sua chave secreta do JWT em locais seguros, como variáveis de ambiente (usando dotenv ou configurando no servidor de produção). Jamais deixe esse segredo exposto no código fonte ou em repositórios. Considere também rotacionar a chave periodicamente se aplicável.

• Curto prazo de expiração e refresh tokens: Defina um tempo de expiração razoável para os tokens de acesso JWT – por exemplo, tokens que expiram em 15 minutos, 1 hora, etc. Isso limita a janela de uso indevido caso um token vaze. Se sua aplicação precisar manter usuários logados por longos períodos sem pedir login de novo, implemente um Refresh Token: um token separado, de longa duração, armazenado de forma segura (idealmente em um cookie httpOnly), usado para obter novos JWTs de acesso quando estes expirarem. Assim você mantém o access token (JWT principal) com vida curta e melhora a segurança.

• HTTPS sempre: Tokens JWT não são criptografados por si só, apenas codificados. Se alguém interceptar a comunicação, pode roubar o token e usá-lo enquanto válido (ataque de replay). Portanto, nunca transmita JWTs em conexões não seguras. Em produção, sua API deve estar sob HTTPS (TLS). Isso garante que mesmo que o token circule em headers, ele não será exposto a bisbilhoteiros de rede. Segurança de API REST começa com HTTPS – não abra mão disso.

• Não confie só no cliente: Mesmo com JWT protegendo suas rotas, sempre valide entradas e restrinja acessos do lado do servidor. O token pode te dizer quem é o usuário e quais privilégios ele tem, mas cabe à sua lógica de negócio aplicar essas restrições. No nosso exemplo, fizemos um check simples de user.role para a rota admin. Em apps reais, desenhe bem as regras de autorização (quem pode acessar o quê) e implemente essas verificações consistentemente. Lembre-se: autenticação verifica identidade (token válido? quem é?), autorização verifica permissões (pode ou não pode fazer tal ação). Ambas são importantes.

• Estruture o código separando responsabilidades: Uma dica de arquitetura é manter a lógica de autenticação separada da lógica de negócio da sua aplicação. Por exemplo, no Fastify criamos um decorator authenticate reutilizável e aplicamos via hook nas rotas. Poderíamos extrair isso para um plugin próprio de autenticação (usando fastify-plugin) e até isolar as rotas de /login e semelhantes em um módulo à parte. Dessa forma, se amanhã você precisar alterar detalhes do auth (algoritmo JWT, formato do payload, etc.), consegue fazê-lo sem mexer nos handlers de rotas de negócio. Essa separação limpa deixa o código mais manutenível e claro.

• Bibliotecas confiáveis e algoritmos seguros: O Fastify JWT plugin que usamos é construído sobre a popular biblioteca jsonwebtoken do Node, que já implementa todos os detalhes do padrão JWT para você. Sempre prefira utilizar essas bibliotecas consolidadas em vez de tentar "fazer seu próprio JWT na unha". Elas cuidam de detalhes como algoritmos de hashing, manipulação de tempo de expiração, entre outros, reduzindo chances de erro. Configure-as corretamente (por exemplo, especifique algoritmos se quiser restringir a um específico) e mantenha-as atualizadas para se beneficiar de correções de segurança.

• JWT não é bala de prata: Embora excelente para muitas situações, JWT também tem seus desafios. Por exemplo, uma vez emitido, até expirar ele é válido – se um usuário teve privilégios alterados (ex: foi banido ou mudou de role), o token antigo ainda pode dar acesso até expirar. Nesses casos, pode ser necessário implementar token revocation ou diminuir o tempo de vida. Além disso, o tamanho do JWT cresce conforme coloca mais dados no payload, então inclua apenas o necessário (por exemplo, não coloque um objeto enorme de usuário, apenas um ID e claims essenciais). Use o JWT para o que ele é bom: transmitir identidade/claims e verificar autenticidade, não como armazenamento de dados arbitrários.

Conclusão e próximos passos