Como Usar JWT com Express.js: Guia Completo de Autenticação

O uso de JWT (JSON Web Token) em aplicações construídas com Express.js é uma das formas mais eficientes e seguras de implementar autenticação em APIs RESTful. Além disso, ao integrar Refresh Token, é possível oferecer uma experiência contínua ao usuário, mesmo com tokens de acesso de curta duração.

O que é JWT?

JWT (JSON Web Token) é um padrão aberto usado para transmitir informações de forma segura entre sistemas. Ele é amplamente utilizado para autenticação em APIs REST, pois permite verificar a identidade do usuário com base em um token assinado digitalmente.

Um JWT é composto por três partes principais:

• Header: define o tipo do token e o algoritmo de assinatura
• Payload: contém os dados do usuário e metadados, como data de expiração
• Signature: garante a integridade do token, impedindo alterações não autorizadas

Por Que Usar JWT com Express.js?

Express.js é um dos frameworks mais populares para desenvolver servidores HTTP com Node.js. Quando combinado ao JWT, ele oferece vantagens importantes:

• Arquitetura stateless: não depende de sessões armazenadas no servidor
• Escalabilidade: fácil de usar em microsserviços e arquiteturas distribuídas
• Compatibilidade: trabalha bem com front-ends modernos, como React, Angular e Flutter

Essa combinação é ideal para projetos que precisam de segurança, simplicidade e desempenho.

Configurando JWT com Express.js

1. Instale as Dependências Necessárias

Para começar, instale o Express e a biblioteca jsonwebtoken:

npm install express jsonwebtoken

Também é recomendável usar dotenv para gerenciar variáveis de ambiente:

npm install dotenv

2. Crie um Middleware para Verificação do Token

Você pode criar um middleware reutilizável para verificar tokens nas rotas protegidas:

// middleware/authJwt.js
const jwt = require('jsonwebtoken');

const authJwt = (req, res, next) => {
    const token = req.header('x-access-token');

    if (!token) {
        return res.status(403).json({ message: 'Token não fornecido' });
    }

    try {
        const decoded = jwt.verify(token, process.env.JWT_SECRET);
        req.user = decoded;
        next();
    } catch (err) {
        return res.status(401).json({ message: 'Token inválido' });
    }
};

module.exports = authJwt;

Este middleware extrai o token do cabeçalho da requisição, verifica sua validade e, se correto, adiciona os dados do usuário ao objeto req.

3. Gere Tokens em Rotas de Login

Crie uma rota de login que gere tokens após validar as credenciais do usuário:

// routes/auth.js
const jwt = require('jsonwebtoken');
const express = require('express');
const router = express.Router();

router.post('/login', (req, res) => {
    // Simulando usuário autenticado
    const user = {
        id: 1,
        username: 'usuario',
        role: 'user'
    };

    const accessToken = jwt.sign(user, process.env.JWT_SECRET, { expiresIn: '15m' });

    res.json({ accessToken });
});

module.exports = router;

Aqui, o token tem uma vida útil curta (15 minutos), aumentando a segurança da aplicação.

Entendendo o Refresh Token

O Refresh Token é um mecanismo que permite renovar o token de acesso sem exigir que o usuário faça login novamente. Ele costuma ter uma validade maior e é usado apenas para obter novos tokens de acesso.

Esse modelo oferece segurança adicional, já que:

• Os tokens de acesso são curtos e menos propensos a serem explorados
• O refresh token é armazenado com cuidado e pode ser revogado individualmente
• Reduz a necessidade de reautenticação frequente

Implementando Refresh Token com Express.js

1. Armazene Refresh Tokens de Forma Segura

Ao contrário do token de acesso, o refresh token deve ser armazenado com segurança extra. Recomenda-se:

• Salvar no banco de dados com hash
• Associar ao usuário e verificar validade
• Impedir uso múltiplo (anti-replay)

Exemplo de geração de refresh token:

const refreshToken = jwt.sign({ id: user.id }, process.env.JWT_REFRESH_SECRET, { expiresIn: '7d' });

2. Crie a Rota para Atualizar o Token de Acesso

// routes/auth.js
router.post('/refresh-token', (req, res) => {
    const { refreshToken } = req.body;

    if (!refreshToken) {
        return res.status(403).json({ message: 'Refresh token não fornecido' });
    }

    try {
        const decoded = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);

        const newAccessToken = jwt.sign(
            { id: decoded.id },
            process.env.JWT_SECRET,
            { expiresIn: '15m' }
        );

        res.json({ accessToken: newAccessToken });
    } catch (err) {
        return res.status(401).json({ message: 'Refresh token inválido' });
    }
});

Esta rota recebe o refresh token, valida-o e retorna um novo token de acesso caso seja válido.

Estrutura Final do Projeto

Sua estrutura básica deve seguir este padrão:

meu-projeto/
│
├── middleware/
│   └── authJwt.js
│
├── routes/
│   ├── auth.js
│   └── protected.js
│
├── .env
├── app.js
└── package.json

No arquivo .env, defina suas chaves secretas:

JWT_SECRET=sua_chave_secreta_para_access_token
JWT_REFRESH_SECRET=sua_chave_secreta_para_refresh_token

Conclusão

Integrar JWT com Express.js é uma solução prática e eficaz para implementar autenticação em aplicações web modernas. Ao adicionar Refresh Token, você melhora a experiência do usuário sem comprometer a segurança.

Essa abordagem é especialmente útil para APIs REST, sistemas stateless e arquiteturas escaláveis, sendo uma escolha sólida tanto para projetos pequenos quanto corporativos.