🔐 2.10 · API REST con autenticación JWT: protege tu backend

🎯 Objetivo del tema

🗺️ Mapa del tema

Hasta ahora, tu API es PÚBLICA: cualquiera puede hacer GET, POST, DELETE sin ninguna restricción. En el mundo real, necesitas controlar QUIÉN puede hacer QUÉ: solo el dueño de un post puede editarlo, solo usuarios logueados pueden comentar, solo admins pueden borrar usuarios. JWT (JSON Web Tokens) es el estándar moderno para esto: compacto, sin estado, escalable, y portable entre lenguajes.

2.10.1 Autenticación vs autorización

Dos conceptos que se confunden constantemente: autenticación es 'quién eres', autorización es 'qué puedes hacer'. Son pasos distintos y tu API los maneja por separado. Primero autenticas (login), después autorizas (¿este usuario puede hacer esto?).

2.10.2 REST: las 4 reglas que tu API debe seguir

REST (Representational State Transfer) es un ESTILO de arquitectura para APIs web, no un estándar rígido. Las buenas APIs REST tienen 4 características: son stateless, usan URLs para representar recursos, verbos HTTP para acciones, y JSON como formato de respuesta. Si tu API sigue estas reglas, es RESTful.

2.10.3 JWT: estructura, firma, verificación

Un JWT (JSON Web Token) es un string con 3 partes separadas por puntos: header.payload.signature. El header dice qué algoritmo se usó. El payload contiene los datos (claims). La signature verifica que el token no fue alterado. Es COMPACTO (cabe en una cookie o un header), SIN ESTADO (el servidor no guarda nada) y PORTABLE (cualquier servidor puede verificarlo).

// Un JWT de ejemplo:
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjQyLCJyb2wiOiJhZG1pbiIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDAzNjAwfQ.7v8X3qGvBhC0dE4sWqXjKp2z0gN3p9wY5sF4nL6kM2c
//   \_HEADER_/   \_/___________________PAYLOAD___________________________/    \_SIGNATURE_/

// Decodificado:
// Header:  { alg: 'HS256', typ: 'JWT' }
// Payload: { userId: 42, rol: 'admin', iat: 1700000000, exp: 1700003600 }
// Signature: HMACSHA256(base64UrlEncode(header) + '.' + base64UrlEncode(payload), secret)

// La signature se calcula con un SECRET que solo el servidor conoce.
// Si alguien cambia el payload, la signature no coincide, y el token es INVÁLIDO.

Estructura de un JWT

2.10.4 Login y registro: bcrypt y jsonwebtoken

El flujo de autenticación: el usuario se REGISTRA (email + contraseña), el servidor hashea la contraseña y guarda el hash. En el LOGIN, el usuario envía sus credenciales, el servidor las compara con el hash, y si coinciden emite un JWT. El cliente guarda el JWT y lo envía en cada petición protegida.

// auth/register.js: registrar un usuario
import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';
import { Usuario } from '../models/Usuario.js';

export const registrar = asyncHandler(async (req, res) => {
  const { email, password, nombre } = req.body;

  // 1. Validar (en Mongoose con validators: true)
  if (!email || !password) {
    return res.status(400).json({ error: 'Email y password requeridos' });
  }

  // 2. Verificar que no exista
  const existe = await Usuario.findOne({ email });
  if (existe) return res.status(409).json({ error: 'Email ya registrado' });

  // 3. HASHEAR la contraseña (NUNCA guardar en texto plano)
  const passwordHash = await bcrypt.hash(password, 12);  // 12 = salt rounds

  // 4. Crear el usuario
  const usuario = await Usuario.create({ email, password: passwordHash, nombre });

  // 5. Emitir un JWT
  const token = jwt.sign(
    { userId: usuario._id, rol: usuario.rol },
    process.env.JWT_SECRET,
    { expiresIn: '1h' }
  );

  res.status(201).json({ usuario: { id: usuario._id, email, nombre }, token });
});

// auth/login.js: iniciar sesión
export const login = asyncHandler(async (req, res) => {
  const { email, password } = req.body;

  const usuario = await Usuario.findOne({ email });
  if (!usuario) return res.status(401).json({ error: 'Credenciales inválidas' });

  // Comparar la contraseña con el hash
  const ok = await bcrypt.compare(password, usuario.password);
  if (!ok) return res.status(401).json({ error: 'Credenciales inválidas' });

  // Emitir JWT (igual que en register)
  const token = jwt.sign(
    { userId: usuario._id, rol: usuario.rol },
    process.env.JWT_SECRET,
    { expiresIn: '1h' }
  );

  res.json({ usuario: { id: usuario._id, email, nombre }, token });
});

Registro y Login con bcrypt y JWT

2.10.5 Middleware de autenticación en Express

Un middleware de autenticación verifica el JWT en cada petición protegida. Si el token es válido, añade req.user con los datos del usuario para que las rutas puedan usarlos. Si no, devuelve 401 Unauthorized. Es la forma estándar de proteger rutas en Express.

// middleware/auth.js: middleware de autenticación
import jwt from 'jsonwebtoken';
import { Usuario } from '../models/Usuario.js';

export const authMiddleware = asyncHandler(async (req, res, next) => {
  // 1. Leer el header Authorization: Bearer <token>
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Token no proporcionado' });
  }
  const token = authHeader.split(' ')[1];

  try {
    // 2. Verificar el token
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    // 3. Cargar el usuario (opcional, para tener datos frescos)
    const usuario = await Usuario.findById(decoded.userId).select('-password');
    if (!usuario) return res.status(401).json({ error: 'Usuario no existe' });

    // 4. Añadir req.user para las rutas
    req.user = usuario;
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Token inválido o expirado' });
  }
});

// middleware/admin.js: solo admins
export const adminMiddleware = (req, res, next) => {
  if (req.user?.rol !== 'admin') {
    return res.status(403).json({ error: 'Requiere rol admin' });
  }
  next();
};

// Uso en rutas:
import { authMiddleware, adminMiddleware } from '../middleware/auth.js';

router.get('/perfil', authMiddleware, (req, res) => {
  res.json(req.user);  // req.user viene del middleware
});

router.delete('/usuarios/:id', authMiddleware, adminMiddleware, async (req, res) => {
  // Solo usuarios autenticados Y con rol admin pueden borrar
  await Usuario.findByIdAndDelete(req.params.id);
  res.status(204).send();
});

Middleware de autenticación y de admin

2.10.6 Refresh tokens y logout

Un JWT con expiración corta (1h) es seguro, pero incomodo: el usuario tiene que hacer login cada hora. La solución profesional: access token corto (1h) + refresh token largo (7-30 días). El access token se usa para peticiones; cuando expira, el refresh token (que está en una cookie httpOnly) permite obtener uno nuevo sin que el usuario haga login de nuevo.

// auth/refresh.js: obtener un nuevo access token
import jwt from 'jsonwebtoken';

export const refresh = asyncHandler(async (req, res) => {
  // El refresh token viene en una cookie httpOnly (no accesible por JS)
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) {
    return res.status(401).json({ error: 'No refresh token' });
  }

  try {
    const decoded = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);
    const newAccessToken = jwt.sign(
      { userId: decoded.userId, rol: decoded.rol },
      process.env.JWT_SECRET,
      { expiresIn: '1h' }
    );
    res.json({ token: newAccessToken });
  } catch (err) {
    res.status(401).json({ error: 'Refresh token inválido' });
  }
});

// auth/logout.js: cerrar sesión (borrar el refresh token)
export const logout = (req, res) => {
  res.clearCookie('refreshToken');
  res.json({ mensaje: 'Sesión cerrada' });
};

Refresh token y logout

📚 Contenido ampliado

Material adicional, referencias externas verificadas y ejemplos extendidos.