RFC 7519 · JSON Web Signature

Introducción a JWT

JSON Web Token (JWT) es un estándar abierto (RFC 7519) para representar claims como una cadena compacta y segura para URL. Se usa mucho con OAuth 2.0 y OpenID Connect, pero el formato es genérico: quien tenga el material de verificación adecuado puede comprobar la firma y razonar sobre los claims, dentro de los límites de la gestión de claves y relojes.

Esta página explica cómo se construye un JWT, cómo leer cada parte y qué garantías puedes —y no puedes— esperar solo del token.

01

Serialización compacta y codificación

En la forma habitual (JSON Web Signature, JWS), un JWT tiene tres segmentos separados por puntos: cabecera, payload y firma. Los dos primeros son objetos JSON codificados en Base64URL (no Base64 clásica): a menudo sin padding y con caracteres seguros para URL.

Base64URL no es cifrado. La cabecera y el payload son legibles para quien tenga la cadena. La firma prueba que las dos primeras partes las produjo quien controla la clave; no oculta su contenido.

02

Estructura de un JWT

Cada segmento tiene un papel en la forma compacta JWS:

Cabecera

Suele incluir typ (tipo, a menudo "JWT") y alg (algoritmo). Puede llevar kid para elegir la clave pública en un JWKS u otros metadatos.

Payload

Objeto JSON con claims: sujeto, ventana de validez, audiencia y campos propios. Se permiten objetos anidados si el emisor lo define.

Firma

Valor criptográfico sobre los bytes de "cabecera.payload" (los dos segmentos codificados y el punto), con el algoritmo de la cabecera y secreto compartido (HMAC) o clave privada asimétrica (RSA, ECDSA, EdDSA).

03

Claims: qué hay en el payload

Los claims son pares nombre/valor. Su significado depende del contexto, pero RFC 7519 define nombres registrados para interoperar.

Claims registrados

Ejemplos: iss, sub, aud, exp, nbf, iat, jti. exp y nbf son timestamps Unix; validarlos bien requiere un reloj de confianza en el verificador.

Claims públicos

Los nombres pueden registrarse en IANA cuando buscas interoperabilidad amplia. Siguen siendo convenciones hasta que productor y consumidor acuerden.

Claims privados

Nombres acordados entre emisor y consumidor (p. ej. roles internos). Evita colisiones con nombres registrados salvo que controles ambos lados.

04

Algoritmos en resumen

El valor alg en la cabecera define cómo se calcula la firma. Elegir mal el modelo afecta quién puede verificar y cómo se comparten secretos.

  • HMAC (HS*): un secreto compartido firma y verifica. Simple para un solo servicio, pero todo verificador debe tener el secreto.
  • RSA o ECDSA/EdDSA: el emisor firma con clave privada; los verificadores usan la pública (a menudo vía JWKS). Encaja en microservicios y clientes que no deben tener secretos de firma.
  • El algoritmo "none" no debe aceptarse en producción: permitiría tokens sin firma si está mal configurado. Rechaza algoritmos desconocidos o deshabilitados.
05

Seguridad: confianza, privacidad y validación

Una firma válida muestra que el token lo emitió quien controla la clave y que cabecera y payload no se alteraron. Por sí sola no cifra nada.

No pongas contraseñas, API keys ni secretos de larga duración en el payload. Para confidencialidad además de firma, usa TLS y considera JWE —otro formato y flujo.

Los servidores deben validar la firma con la clave o JWKS esperados, comprobar exp (y suele nbf), aplicar aud e iss si la arquitectura lo requiere, y usar vidas cortas y refresh cuando corresponda.

06

Usos habituales

Los JWT suelen usarse para:

  • Representar identidad y autorización (tokens de acceso, ID tokens en OpenID Connect)
  • Propagar identidad o delegación entre servicios
  • Modelar sesión en clientes con almacenamiento seguro y estrategias de refresh
  • Llevar scopes OAuth 2.0 o claims personalizados en gateways y servidores de recursos
07

Límites prácticos

Restricciones útiles al diseñar con JWT:

  • Tamaño: suelen ir en cabeceras HTTP; payloads grandes aumentan latencia y pueden chocar con límites de proxy.
  • Revocación: un JWT puramente sin estado no se revoca al instante sin infraestructura extra (listas de denegación, introspección o vidas muy cortas).
  • Deriva de reloj: la validación de exp y nbf depende de relojes razonablemente sincronizados entre emisores y verificadores.