StackPractices
intermediate Por Mathias Paulenko

Autenticación JWT en Node.js: Verificar y Refrescar Tokens

Implementa autenticación JWT en Node.js: access y refresh tokens, rotación con detección de reuso y middleware de Express

Visión General

JWT le da a una API de Node.js autenticación stateless: el servidor firma un token con los claims del usuario y cada petición lo presenta en el header Authorization, sin consultar un store de sesiones en cada llamada. Esta recipe construye el flujo completo en Express con jsonwebtoken: emitir access y refresh tokens, proteger rutas con middleware, rotar refresh tokens y detectar reuso. Para la versión multi-lenguaje que también cubre Python y Java, mira la recipe Autenticación JWT.

Cuándo Usar

  • Estás construyendo una API Express stateless y necesitas auth sin sesiones del lado del servidor
  • Quieres access tokens de corta duración respaldados por refresh tokens de larga duración
  • Necesitas rotación de refresh tokens para contener el daño de un token robado
  • Tus microservicios verifican tokens de forma independiente con un secreto compartido o una clave pública

Evítalo cuando:

  • Una sesión del lado del servidor ya resuelve el problema — un monolito con un solo frontend web suele ser más simple con cookies de sesión
  • Delegas la autenticación a un proveedor OAuth; en ese caso ve a Login OAuth2 con GitHub en Node.js y Express
  • Necesitas revocación instantánea por petición — un JWT sigue válido hasta que expira salvo que mantengas una blocklist en el servidor

Solución

Generación y verificación básica de JWT

const jwt = require("jsonwebtoken");

const ACCESS_TOKEN_SECRET = process.env.JWT_ACCESS_SECRET || "access-secret-change-me";
const REFRESH_TOKEN_SECRET = process.env.JWT_REFRESH_SECRET || "refresh-secret-change-me";

function generateAccessToken(payload) {
    return jwt.sign(payload, ACCESS_TOKEN_SECRET, {
        expiresIn: "15m",
        issuer: "my-api",
        audience: "my-api-users"
    });
}

function generateRefreshToken(payload) {
    return jwt.sign(payload, REFRESH_TOKEN_SECRET, {
        expiresIn: "7d",
        issuer: "my-api",
        audience: "my-api-users"
    });
}

function verifyAccessToken(token) {
    try {
        return jwt.verify(token, ACCESS_TOKEN_SECRET, {
            issuer: "my-api",
            audience: "my-api-users"
        });
    } catch (err) {
        if (err.name === "TokenExpiredError") {
            return { error: "token_expired" };
        }
        return { error: "invalid_token" };
    }
}

// Usage
const user = { userId: 123, role: "admin" };
const accessToken = generateAccessToken(user);
const decoded = verifyAccessToken(accessToken);
console.log(decoded);

Middleware de Express para autenticación JWT

const express = require("express");
const jwt = require("jsonwebtoken");

const app = express();
app.use(express.json());

const ACCESS_TOKEN_SECRET = process.env.JWT_ACCESS_SECRET || "access-secret";

function authMiddleware(req, res, next) {
    const authHeader = req.headers.authorization;

    if (!authHeader || !authHeader.startsWith("Bearer ")) {
        return res.status(401).json({ error: "Missing or invalid authorization header" });
    }

    const token = authHeader.split(" ")[1];

    try {
        const decoded = jwt.verify(token, ACCESS_TOKEN_SECRET, {
            issuer: "my-api",
            audience: "my-api-users"
        });
        req.user = decoded;
        next();
    } catch (err) {
        if (err.name === "TokenExpiredError") {
            return res.status(401).json({ error: "Token expired", code: "token_expired" });
        }
        return res.status(401).json({ error: "Invalid token", code: "invalid_token" });
    }
}

function requireRole(role) {
    return (req, res, next) => {
        if (!req.user || req.user.role !== role) {
            return res.status(403).json({ error: "Insufficient permissions" });
        }
        next();
    };
}

app.get("/api/public", (req, res) => {
    res.json({ message: "public endpoint" });
});

app.get("/api/profile", authMiddleware, (req, res) => {
    res.json({ user: req.user });
});

app.get("/api/admin", authMiddleware, requireRole("admin"), (req, res) => {
    res.json({ message: "admin only" });
});

app.listen(3000, () => console.log("Server running on port 3000"));

Flujo de login y refresh token

const express = require("express");
const jwt = require("jsonwebtoken");
const crypto = require("crypto");
const bcrypt = require("bcrypt");

const app = express();
app.use(express.json());

const ACCESS_TOKEN_SECRET = process.env.JWT_ACCESS_SECRET || "access-secret";
const REFRESH_TOKEN_SECRET = process.env.JWT_REFRESH_SECRET || "refresh-secret";

// Store de refresh tokens en memoria, indexado por hash del token — lookup O(1) (usa Redis en producción)
const refreshTokens = new Map();
const tokenKey = (token) => crypto.createHash("sha256").update(token).digest("hex");

// Base de datos de usuarios de ejemplo — genera el hash con bcrypt.hashSync("admin123", 12)
const users = [
    { id: 1, username: "admin", password: "$2b$12$REPLACE_WITH_REAL_BCRYPT_HASH", role: "admin" }
];

app.post("/auth/login", async (req, res) => {
    const { username, password } = req.body;

    const user = users.find(u => u.username === username);
    if (!user || !(await bcrypt.compare(password, user.password))) {
        return res.status(401).json({ error: "Invalid credentials" });
    }

    const payload = { userId: user.id, role: user.role };
    const accessToken = jwt.sign(payload, ACCESS_TOKEN_SECRET, { expiresIn: "15m" });
    const refreshToken = jwt.sign(payload, REFRESH_TOKEN_SECRET, { expiresIn: "7d" });

    refreshTokens.set(tokenKey(refreshToken), { userId: user.id });

    res.json({
        accessToken,
        refreshToken,
        expiresIn: 900
    });
});

app.post("/auth/refresh", (req, res) => {
    const { refreshToken } = req.body;

    if (!refreshToken) {
        return res.status(400).json({ error: "Refresh token required" });
    }

    try {
        const decoded = jwt.verify(refreshToken, REFRESH_TOKEN_SECRET);

        // Verifica que el token esté en el store (no revocado)
        if (!refreshTokens.has(tokenKey(refreshToken))) {
            return res.status(401).json({ error: "Token revoked" });
        }

        // Generate new access token
        const newAccessToken = jwt.sign(
            { userId: decoded.userId, role: decoded.role },
            ACCESS_TOKEN_SECRET,
            { expiresIn: "15m" }
        );

        res.json({ accessToken: newAccessToken, expiresIn: 900 });
    } catch (err) {
        return res.status(401).json({ error: "Invalid refresh token" });
    }
});

app.post("/auth/logout", (req, res) => {
    refreshTokens.delete(tokenKey(req.body.refreshToken));

    res.json({ message: "Logged out" });
});

app.listen(3000);

Rotación de tokens con detección de reuso

Este ejemplo continúa desde el setup de Express anterior — app es la misma instancia y ambos secrets vienen de variables de entorno.

const jwt = require("jsonwebtoken");
const crypto = require("crypto");

const ACCESS_TOKEN_SECRET = process.env.JWT_ACCESS_SECRET || "access-secret";
const REFRESH_TOKEN_SECRET = process.env.JWT_REFRESH_SECRET || "refresh-secret";

// Store: { jti: { userId, token, family, createdAt } }
const tokenStore = new Map();

function generateRotatedRefreshToken(userId, family) {
    const jti = crypto.randomUUID();
    const token = jwt.sign({ userId, jti, family }, REFRESH_TOKEN_SECRET, { expiresIn: "7d" });

    tokenStore.set(jti, { userId, token, family, createdAt: Date.now() });

    return token;
}

function rotateRefreshToken(oldToken) {
    let decoded;
    try {
        decoded = jwt.verify(oldToken, REFRESH_TOKEN_SECRET);
    } catch (err) {
        throw new Error("invalid_token");
    }

    const stored = tokenStore.get(decoded.jti);

    if (!stored) {
        // Token was already used — possible reuse attack
        // Revoke entire family
        for (const [jti, data] of tokenStore.entries()) {
            if (data.family === decoded.family) {
                tokenStore.delete(jti);
            }
        }
        throw new Error("reuse_detected");
    }

    if (stored.token !== oldToken) {
        throw new Error("invalid_token");
    }

    // Delete old token
    tokenStore.delete(decoded.jti);

    // Issue new token in same family
    return generateRotatedRefreshToken(decoded.userId, decoded.family);
}

// Usage in Express route
app.post("/auth/refresh", (req, res) => {
    try {
        const newRefreshToken = rotateRefreshToken(req.body.refreshToken);
        const decoded = jwt.verify(newRefreshToken, REFRESH_TOKEN_SECRET);
        const accessToken = jwt.sign(
            { userId: decoded.userId },
            ACCESS_TOKEN_SECRET,
            { expiresIn: "15m" }
        );

        res.json({ accessToken, refreshToken: newRefreshToken });
    } catch (err) {
        if (err.message === "reuse_detected") {
            return res.status(401).json({
                error: "Token reuse detected. All sessions revoked.",
                code: "reuse_detected"
            });
        }
        return res.status(401).json({ error: "Invalid refresh token" });
    }
});

Tokens asimétricos RS256

const fs = require("fs");
const jwt = require("jsonwebtoken");

const privateKey = fs.readFileSync("private.key", "utf8");
const publicKey = fs.readFileSync("public.key", "utf8");

function signToken(payload) {
    return jwt.sign(payload, privateKey, {
        algorithm: "RS256",
        expiresIn: "15m"
    });
}

function verifyToken(token) {
    try {
        return jwt.verify(token, publicKey, { algorithms: ["RS256"] });
    } catch (err) {
        return { error: err.message };
    }
}

Explicación

Un JWT tiene tres partes separadas por puntos: header (el algoritmo), payload (claims como userId, role, exp, iat, iss, aud) y signature. jwt.verify recalcula la firma y rechaza el token si algo fue alterado — por eso no hace falta consultar una base de datos para autenticar una petición.

Conceptos clave:

  • Access tokens: corta duración a propósito (15 minutos aquí). El cliente envía uno en cada petición de API y el servidor lo verifica sin estado — sin lookup a ningún store.
  • Refresh tokens: larga duración (7 días aquí) y solo se intercambian por nuevos access tokens. Como pueden emitir nuevas sesiones, viven en un store del lado del servidor para poder revocarlos.
  • Rotación de tokens: cada refresh quema el token viejo y emite uno nuevo. Si un token ya quemado aparece de nuevo, trátalo como robo — la familia entera de tokens se revoca y el usuario vuelve a hacer login.
  • HS256 vs RS256: HS256 comparte un único secreto entre quien firma y quien verifica. RS256 firma con una clave privada y verifica con una pública, así que un servicio comprometido que solo lee no puede forjar tokens.

Cómo funciona la rotación con detección de reuso

Rotación de refresh tokens con detección de reuso — cuando se presenta un token ya consumido, el servidor revoca toda la familia de tokens

Notas de producción

  • Secrets: los fallbacks || "access-secret" existen para que el snippet corra en local. En producción, carga ambos secrets desde variables de entorno o un gestor de secretos y falla rápido al arrancar si faltan — un fallback desplegado es una cadena conocida con la que cualquiera puede firmar.
  • Store de refresh: el Map de aquí muere con el proceso y no escala más allá de una instancia. Muévelo a Redis indexado por el hash del token (igual que tokenKey arriba) con un TTL igual a la vida del token; la lógica de revocación queda idéntica.
  • Transporte: para clientes de navegador, envía el refresh token como cookie httpOnly, Secure, SameSite=Strict en vez de un campo JSON — JavaScript no puede leerla y el riesgo de CSRF queda bajo. El access token puede vivir en memoria y nunca tocar localStorage.
  • Elección de librería: jsonwebtoken sigue siendo lo que usa la mayoría de codebases Express, por eso lo emplean los ejemplos. En ESM, edge runtimes o donde quieras WebCrypto, jose cubre los mismos flujos con una API más moderna.

Variantes

EnfoqueAlgoritmoStorageUsar Cuando
HS256SimétricoShared secretServidor único, setup simple
RS256AsimétricoPar de llavesMicroservicios, verificadores con clave pública
ES256AsimétricoEC key pairApps móviles, dispositivos restringidos
Redis-backedHS256RedisStore de refresh compartido entre varias instancias de la app
Database-backedHS256SQLCuando Redis no está disponible

Buenas Prácticas

  • Firma los access y refresh tokens con secrets distintos — una filtración de uno queda contenida.
  • Mantén los access tokens en 15 minutos o menos y deja que el refresh token cargue con la sesión larga.
  • Guarda los refresh tokens del lado del servidor; un refresh token puramente stateless no se puede revocar.
  • Rota los refresh tokens y detecta el reuso — es la señal más barata de que un token fue robado.
  • Usa RS256 en microservicios para que los verificadores solo tengan la clave pública y nunca puedan firmar.
  • Configura los claims issuer y audience para que un token emitido para un servicio sea rechazado por otro.
  • Nunca guardes tokens en localStorage en apps de navegador. Usa cookies httpOnly.

Errores Comunes

  • Usar el mismo secret para access y refresh tokens — una filtración y el atacante puede emitir ambos.
  • Saltarse la validación de issuer y audience, que deja pasar por el middleware un token emitido para otro servicio.
  • Guardar tokens en localStorage, donde cualquier payload XSS puede leerlos. Las cookies httpOnly están fuera del alcance de JavaScript.
  • Mantener los refresh tokens puramente stateless — sin registro en el servidor no hay nada que revocar, así que el logout no hace nada.
  • Access tokens de larga duración. Un token robado de una hora es una hora de acceso gratis; quince minutos achican esa ventana a algo que el atacante apenas puede usar.

Lecturas Adicionales

Preguntas frecuentes

¿Debo usar JWT o sesiones del lado del servidor?

Usa JWT cuando la API necesite escalar horizontalmente sin un store de sesiones compartido — cada servicio verifica el token por su cuenta. Para un monolito, las sesiones del lado del servidor son más simples de revocar y más fáciles de razonar.

¿Cómo revoco un JWT antes de que expire?

Un access token sigue válido hasta que expira — no hay forma de matarlo antes sin consultar una denylist de claims jti en el servidor. Por eso esta recipe los mantiene en 15 minutos. Los refresh tokens son distintos: viven en un store del lado del servidor de todos modos, así que revócalos en cuanto el usuario cierre sesión o aparezca un intento de reuso.

¿Cuál es la diferencia entre HS256 y RS256?

Con HS256, cada servicio que verifica un token también tiene el secreto de firma — fíltralo una vez y un atacante puede emitir tokens. RS256 separa los papeles: el servicio de auth firma con la clave privada y todos los demás verifican con la pública, que no puede firmar nada.

¿Cómo manejo la expiración de tokens elegantemente?

Devuelve un código token_expired diferenciado para que el cliente distinga un token expirado de una firma inválida, luego refresca y reintenta la petición una vez:

if (error.response.status === 401 && error.response.data.code === "token_expired") {
    const newToken = await refreshToken();
    retryOriginalRequest(newToken);
}