¿Qué es un JWT?

Si has creado alguna aplicación web moderna que gestione la autenticación, casi seguro que has trabajado con un JSON Web Token, abreviado habitualmente como JWT (se pronuncia “jot”). Un JWT es una forma compacta y segura para URL de representar un conjunto de claims entre dos partes. Está definido en el RFC 7519 y se ha convertido en el estándar de facto para la autenticación sin estado en las API REST.

Entendiendo JWT (JSON Web Token) y cómo depurarlo

La palabra clave es sin estado. A diferencia de la autenticación tradicional basada en sesiones, en la que el servidor guarda los datos de sesión en memoria o en una base de datos, los JWT llevan toda la información necesaria dentro del propio token. El servidor no necesita consultar nada: simplemente verifica la firma y confía en el contenido.

Un JWT en bruto tiene este aspecto:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsInJvbGUiOiJhZG1pbiIsImV4cCI6MTczNjkwMDgwMH0.Xe4kJl7YQoLPkZ3r9Vv2mHgGqNtWbF8sDcA1eRfuByk

Son tres segmentos codificados en Base64Url, separados por puntos. Cada segmento tiene un propósito concreto.


La estructura de tres partes

1. Header (cabecera)

La cabecera es un objeto JSON que describe el propio token, sobre todo qué algoritmo se usó para firmarlo.

{
  "alg": "HS256",
  "typ": "JWT"
}

alg indica el algoritmo de firma. Los valores habituales son:

Algoritmo Tipo Notas
HS256 Simétrico (HMAC-SHA256) Un único secreto compartido para firmar y verificar
RS256 Asimétrico (RSA-SHA256) La clave privada firma y la pública verifica
ES256 Asimétrico (ECDSA-SHA256) Claves más pequeñas que RSA, cada vez más popular
none Sin firma Peligroso: no lo aceptes nunca en producción

2. Payload (carga útil)

El payload es donde están los datos reales. Cada dato se llama claim.

{
  "sub": "user_123",
  "name": "Alex Chen",
  "role": "admin",
  "iat": 1736814400,
  "exp": 1736900800
}

Los claims se dividen en tres categorías:

Claims registrados (estandarizados por el RFC 7519):

  • iss (Issuer): quién emitió el token, por ejemplo "https://auth.example.com"
  • sub (Subject): el sujeto al que se refiere el token, normalmente un ID de usuario
  • aud (Audience): a quién va destinado el token
  • exp (Expiration Time): marca de tiempo Unix a partir de la cual el token debe rechazarse
  • iat (Issued At): marca de tiempo Unix de creación del token
  • nbf (Not Before): marca de tiempo Unix antes de la cual el token no debe aceptarse

Claims públicos: definidos en el registro de claims JWT de la IANA o mediante un espacio de nombres URI para evitar colisiones.

Claims privados: claims personalizados acordados entre las partes, como role o plan en el ejemplo anterior.

Recordatorio crítico: el payload solo está codificado, no cifrado. Cualquiera que tenga el token puede leer el payload decodificándolo con Base64. No guardes nunca contraseñas, números de tarjeta de crédito ni otros datos sensibles en el payload de un JWT.

3. Signature (firma)

La firma se calcula así (usando HS256 como ejemplo):

HMAC-SHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

La firma es lo que hace evidente cualquier manipulación de un JWT. Si alguien modifica un solo carácter de la cabecera o del payload, la firma deja de coincidir y el token se rechaza. El servidor no necesita guardar el token en ningún sitio: simplemente vuelve a calcular la firma esperada y la compara con la recibida.


Cómo funciona en la práctica la autenticación con JWT

Un flujo típico es este:

  1. Inicio de sesión: el usuario envía sus credenciales (usuario y contraseña) al endpoint de autenticación.
  2. Emisión del token: el servidor verifica las credenciales, crea un JWT firmado con un secreto o una clave privada y lo devuelve al cliente.
  3. Peticiones posteriores: el cliente incluye el JWT en la cabecera Authorization: Authorization: Bearer <token>.
  4. Verificación: el servidor valida la firma, comprueba exp y lee los claims, todo sin consultar ninguna base de datos.
// Ejemplo de verificación en el servidor (Node.js con la biblioteca jose)
import * as jose from 'jose';

async function verifyRequest(authHeader) {
  const token = authHeader?.split(' ')[1];
  if (!token) throw new Error('No token provided');

  const secret = new TextEncoder().encode(process.env.JWT_SECRET);
  const { payload } = await jose.jwtVerify(token, secret, {
    issuer: 'https://auth.example.com',
    audience: 'https://api.example.com',
  });

  return payload; // { sub, role, exp, ... }
}

JWT frente a tokens de sesión

Ambos enfoques son válidos. La elección depende de tu arquitectura.

Aspecto JWT (sin estado) Token de sesión (con estado)
Almacenamiento en el servidor No hace falta Almacén de sesiones (Redis, BD)
Revocación Difícil: hay que esperar a que caduque o mantener una lista de bloqueo Fácil: se borra del almacén
Escalado horizontal Natural: cualquier servidor puede verificar Requiere un almacén de sesiones compartido
Tamaño del token Mayor (lleva los claims) Pequeño (solo un ID)
Ideal para Microservicios, API, móvil Aplicaciones web tradicionales

Trampas de seguridad habituales

El ataque alg: none

Algunas de las primeras bibliotecas de JWT permitían alg: none, es decir, que no se exigiera firma. Un atacante podía quitar la firma y fabricar un payload arbitrario. Indica siempre de forma explícita qué algoritmos acepta tu servidor y rechaza none.

// jose: seguro por defecto; hay que proporcionar una clave y rechaza los tokens sin firma
await jose.jwtVerify(token, secret); // lanzará un error si alg es "none"

Confusión de algoritmos (RS256 → HS256)

Si un servidor espera RS256 (asimétrico) pero un atacante cambia la cabecera a HS256 (simétrico), algunas bibliotecas usarán la clave pública como secreto HMAC. Como las claves públicas son, bueno, públicas, el atacante puede falsificar tokens válidos. Solución: fija en el servidor qué algoritmos aceptas.

Guardar los JWT en localStorage

Los tokens guardados en localStorage son accesibles para cualquier JavaScript de la página, lo que los hace vulnerables a ataques XSS. Es preferible usar cookies HttpOnly, a las que JavaScript no puede acceder.

Tokens de larga duración sin renovación

Fijar exp en una semana o un mes es tentador, pero significa que un token robado sigue siendo válido mucho tiempo. Usa tokens de acceso de corta duración (15–60 minutos) junto con tokens de renovación de larga duración guardados de forma segura.


Cómo decodificar un JWT manualmente

Como el payload está simplemente codificado en Base64Url, puedes decodificarlo sin ninguna biblioteca:

function decodeJWT(token) {
  const parts = token.split('.');
  if (parts.length !== 3) return null;

  // Base64Url → Base64 → decodificar
  const decode = (str) =>
    JSON.parse(atob(str.replace(/-/g, '+').replace(/_/g, '/')));

  return {
    header:  decode(parts[0]),
    payload: decode(parts[1]),
    // Nota: la firma (parts[2]) no se puede verificar sin el secreto o la clave pública
  };
}

const { header, payload } = decodeJWT('eyJhbGci...');
console.log(payload.exp); // 1736900800

Esto funciona perfectamente para depurar. Pero recuerda: decodificar no es lo mismo que verificar. Verifica siempre la firma en el servidor antes de fiarte de cualquier claim.


Depuración segura en el navegador

Al depurar tokens de un entorno de producción te enfrentas a un dilema: necesitas ver qué hay dentro, pero pegar el JWT de un usuario real en una herramienta en línea de terceros es un riesgo de seguridad. Esos tokens pueden contener IDs de usuario, roles y otros metadatos sensibles.

La Herramienta JWT de DevToolKits procesa tu token íntegramente en tu navegador. No se envía nada a un servidor: puedes comprobarlo tú mismo abriendo la pestaña Red del navegador y viendo que no hay peticiones salientes al pegar un token. También puedes verificar firmas en el cliente proporcionando tu secreto o tu clave pública.


Comprobación de las reclamaciones (avisos)

Aparte de verificar la firma, el depurador de JWT comprueba las reclamaciones del payload decodificado y muestra avisos. Aunque la firma sea válida, tokens como estos dan problemas en producción.

Aviso Condición
Sin exp el token nunca caduca
Vida útil larga exp − iat supera las 24 horas (por ejemplo, 1d 1h)
iat en el futuro más de 60 segundos por delante de la hora actual (se tolera el desfase del reloj)
nbf posterior a exp el token caduca antes de ser válido
Tiempos en milisegundos exp, iat o nbf superan 10^11 (los tiempos de JWT son en segundos)
iss distinto del valor esperado cuando introduce un «Emisor esperado»
aud sin el valor esperado cuando introduce una «Audiencia esperada» (aud puede ser una cadena o una lista, y basta con que coincida alguno)

iss y aud solo se comprueban cuando introduce un valor esperado. Sirve para confirmar que la validación de su API mira siempre iss y aud, y para detectar errores de configuración por entorno, como usar en preproducción el aud de producción.

Novedades de noviembre de 2026

  • Puedes generar un par de claves de prueba (ES256, RS256, PS256, ES384, EdDSA). La clave privada sale como PEM PKCS#8 y JWK, y la pública como PEM SPKI y JWK; «Usar para firmar arriba» rellena el formulario de firma.
  • También se puede firmar con una JWK de clave privada. Las claves se crean en tu navegador y no se envían; solo para pruebas, nunca para producción.

Pruébalo en la herramienta

Preguntas frecuentes

¿Cuál es el tamaño máximo de un JWT?

La especificación de JWT no fija un límite de tamaño, pero existen restricciones prácticas. Las cabeceras HTTP tienen límites (normalmente 8 KB por cabecera) y los navegadores limitan el tamaño de las cookies (unos 4 KB). Mantén el payload ligero: incluye solo los claims que realmente necesitas leer en el lado receptor.

¿Se puede invalidar un JWT antes de que caduque?

No de forma nativa: es una de las contrapartidas de los tokens sin estado. Las soluciones habituales son: (1) mantener en el servidor una lista de bloqueo de IDs de tokens revocados (guardados en el claim jti), (2) usar tiempos de caducidad muy cortos o (3) rotar las claves de firma y mantener una ventana corta de aceptación para las claves antiguas.

¿El cifrado de JWT (JWE) es distinto de la firma de JWT (JWS)?

Sí. Un JWT normal es un JWS (JSON Web Signature): el payload se puede leer, pero cualquier manipulación se detecta. Un JWE (JSON Web Encryption) cifra el payload, de modo que su contenido no se puede leer sin la clave de descifrado. JWS es mucho más habitual; usa JWE solo cuando el propio payload contenga datos que no deban ser visibles durante el tránsito.

¿Debe ser el mismo el secreto del JWT en todos los servicios?

No. Usa claves de firma distintas por servicio o por tipo de token (tokens de acceso frente a tokens de renovación). Así se limita el alcance del daño si una clave se ve comprometida y se facilita la rotación de claves.

¿Cómo gestiono la renovación del token?

Emite un token de acceso de corta duración (por ejemplo, 15 minutos) y un token de renovación de larga duración (por ejemplo, 7 días) guardado en una cookie HttpOnly. Cuando el token de acceso caduca, el cliente envía el token de renovación a un endpoint dedicado, que emite un nuevo token de acceso. El token de renovación debe rotarse (invalidarse y volver a emitirse) en cada uso.