JsonWebToken para JavaScript (Node.js): guia completo com exemplos

O que é e para que serve

A biblioteca JsonWebToken (frequentemente usada como jsonwebtoken ou jwt) é uma das bibliotecas mais populares para trabalhar com JSON Web Tokens (JWT) no ambiente Node.js. JWT é uma forma compacta e autossuficiente de transmitir informações entre partes como um objeto JSON. Essas informações podem ser verificadas e são confiáveis, pois são assinadas digitalmente. Os JWTs podem ser assinados usando uma chave secreta (algoritmo HMAC) ou um par de chaves pública/privada (algoritmos RSA ou ECDSA).

O principal objetivo da biblioteca é implementar mecanismos de autorização e autenticação em aplicações web e APIs. Quando um usuário faz login com sucesso, o servidor cria um JWT e o envia ao cliente. O cliente então envia esse token em cada requisição subsequente, permitindo que o servidor verifique a identidade do usuário sem precisar armazenar dados de sessão no servidor. Isso torna o JWT a solução ideal para criar APIs RESTful, arquiteturas de microsserviços e aplicações de página única (SPA).

A biblioteca jsonwebtoken fornece um conjunto completo de ferramentas para criar (sign), verificar (verify) e decodificar (decode) tokens. Ela suporta todos os algoritmos de assinatura padrão, incluindo HS256, RS256, ES256, e permite configurar flexivelmente o tempo de vida do token, adicionar campos personalizados (claims) e trabalhar com chaves públicas/privadas. Graças à sua confiabilidade e simplicidade, esta biblioteca é usada em milhares de projetos ao redor do mundo e é o padrão de facto para trabalhar com JWT no ecossistema Node.js.

Instalação

Para instalar a biblioteca JsonWebToken no seu projeto Node.js, execute o seguinte comando no terminal:

npm install jsonwebtoken

Se você usa Yarn:

yarn add jsonwebtoken

Após a instalação, você pode importar a biblioteca no seu código:

const jwt = require('jsonwebtoken');
// ou para módulos ES:
// import jwt from 'jsonwebtoken';

Início rápido — exemplo mínimo funcional

Vamos criar um exemplo simples demonstrando a criação e verificação de um token JWT:

const jwt = require('jsonwebtoken');

// Chave secreta (em um projeto real, armazene-a no .env)
const secretKey = 'minha-chave-super-secreta-123';

// Dados que queremos codificar no token (payload)
const payload = {
  userId: 12345,
  username: 'joao_silva',
  role: 'user'
};

// 1. CRIAÇÃO DO TOKEN
const token = jwt.sign(payload, secretKey, { expiresIn: '1h' });
console.log('Token criado:', token);

// 2. VERIFICAÇÃO DO TOKEN
try {
  const decoded = jwt.verify(token, secretKey);
  console.log('Dados decodificados:', decoded);
  // Saída: { userId: 12345, username: 'joao_silva', role: 'user', iat: ..., exp: ... }
} catch (err) {
  console.error('Erro na verificação do token:', err.message);
}

// 3. DECODIFICAÇÃO SEM VERIFICAR ASSINATURA (NÃO RECOMENDADO para autorização!)
const decodedWithoutVerify = jwt.decode(token);
console.log('Decodificado sem verificação:', decodedWithoutVerify);

Este exemplo mostra três operações principais: criação do token com sign(), verificação de autenticidade com verify() e decodificação simples sem verificar a assinatura com decode().