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
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
Mapde 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 quetokenKeyarriba) 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=Stricten 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 tocarlocalStorage. - Elección de librería:
jsonwebtokensigue siendo lo que usa la mayoría de codebases Express, por eso lo emplean los ejemplos. En ESM, edge runtimes o donde quierasWebCrypto,josecubre los mismos flujos con una API más moderna.
Variantes
| Enfoque | Algoritmo | Storage | Usar Cuando |
|---|---|---|---|
| HS256 | Simétrico | Shared secret | Servidor único, setup simple |
| RS256 | Asimétrico | Par de llaves | Microservicios, verificadores con clave pública |
| ES256 | Asimétrico | EC key pair | Apps móviles, dispositivos restringidos |
| Redis-backed | HS256 | Redis | Store de refresh compartido entre varias instancias de la app |
| Database-backed | HS256 | SQL | Cuando 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
issueryaudiencepara 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
issueryaudience, 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
- RFC 7519 — JSON Web Token (JWT) — la especificación detrás de
iss,aud,expy las firmas JWS - OWASP JSON Web Token cheat sheet — checklist de endurecimiento: verificación de algoritmos, almacenamiento, revocación
- jose — JWT para runtimes modernos — la alternativa ESM/WebCrypto mencionada arriba
- Repo complementario — servidor Express ejecutable con un test de flujo que cubre rotación y detección de reuso
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);
}
Recursos Relacionados
Autenticación JWT
Firma, verifica y refresca JWTs en Python, JavaScript y Java — flujos access/refresh, pares de claves RS256 y revocación de tokens bien hecha.
RecipeLogin con OAuth2 de GitHub en Node.js con Express
Implementa el flujo de login OAuth2 de GitHub en Node.js con Express y Passport.
DocPlantilla de Checklist de Seguridad para Endpoints
Una plantilla de checklist para endurecer laptops, estaciones de trabajo y dispositivos móviles que acceden a datos y sistemas corporativos.
RecipeRotacion segura de JWT refresh tokens con Python
Implementa rotacion segura de JWT access y refresh tokens en Python con blacklist, deteccion de reuso y renovacion automatica de access tokens para auth stateless