JsonWebToken en JavaScript (Node.js): guía completa con ejemplos

¿Qué es y para qué sirve?

La librería JsonWebToken (comúnmente usada como jsonwebtoken o jwt) es una de las más populares para trabajar con JSON Web Tokens (JWT) en el entorno Node.js. JWT es una forma compacta y autónoma de transmitir información entre partes como un objeto JSON. Esta información puede ser verificada y es confiable porque está firmada digitalmente. Los JWT pueden firmarse usando una clave secreta (algoritmo HMAC) o un par de claves pública/privada (algoritmos RSA o ECDSA).

El propósito principal de esta librería es implementar mecanismos de autorización y autenticación en aplicaciones web y APIs. Cuando un usuario inicia sesión correctamente, el servidor crea un JWT y lo envía al cliente. Luego, el cliente envía este token en cada solicitud posterior, permitiendo al servidor verificar la identidad del usuario sin necesidad de almacenar datos de sesión en el servidor. Esto hace que JWT sea la solución ideal para crear APIs RESTful, arquitecturas de microservicios y aplicaciones de una sola página (SPA).

La librería jsonwebtoken proporciona un conjunto completo de herramientas para crear (sign), verificar (verify) y decodificar (decode) tokens. Soporta todos los algoritmos de firma estándar, incluyendo HS256, RS256, ES256, y permite configurar de forma flexible el tiempo de vida del token, agregar campos personalizados (claims) y trabajar con claves públicas/privadas. Gracias a su fiabilidad y simplicidad, esta librería se utiliza en miles de proyectos en todo el mundo y es el estándar de facto para trabajar con JWT en el ecosistema Node.js.

Instalación

Para instalar la librería JsonWebToken en tu proyecto Node.js, ejecuta el siguiente comando en la terminal:

npm install jsonwebtoken

Si usas Yarn:

yarn add jsonwebtoken

Después de la instalación, puedes importar la librería en tu código:

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

Inicio rápido — ejemplo mínimo funcional

Creemos un ejemplo sencillo que muestra cómo crear y verificar un token JWT:

const jwt = require('jsonwebtoken');

// Clave secreta (en un proyecto real, guárdala en .env)
const secretKey = 'mi-clave-super-secreta-123';

// Datos que queremos codificar en el token (payload)
const payload = {
  userId: 12345,
  username: 'juan_perez',
  role: 'user'
};

// 1. CREACIÓN DEL TOKEN
const token = jwt.sign(payload, secretKey, { expiresIn: '1h' });
console.log('Token creado:', token);

// 2. VERIFICACIÓN DEL TOKEN
try {
  const decoded = jwt.verify(token, secretKey);
  console.log('Datos decodificados:', decoded);
  // Salida: { userId: 12345, username: 'juan_perez', role: 'user', iat: ..., exp: ... }
} catch (err) {
  console.error('Error al verificar el token:', err.message);
}

// 3. DECODIFICACIÓN SIN VERIFICAR LA FIRMA (NO RECOMENDADO para autorización)
const decodedWithoutVerify = jwt.decode(token);
console.log('Decodificado sin verificar:', decodedWithoutVerify);

Este ejemplo muestra las tres operaciones principales: crear un token con sign(), verificar su autenticidad con verify() y decodificar sin verificar la firma con decode().