Claim (reclamación JWT)

Un claim es un par nombre/valor en un payload JWT que afirma algo sobre el sujeto del token. Los claims son propiedades JSON; el payload es un objeto JSON formado por ellos. Claims estándar definidos en RFC 7519 §4:

• iss — Emisor: quién creó el token.
• sub — Sujeto: sobre quién trata el token (típicamente un ID de usuario).
• aud — Audiencia: para quién está destinado el token. Puede ser una cadena o un array.
• exp — Expiración: segundos Unix después de los cuales el token debe ser rechazado.
• iat — Emitido en: segundos Unix cuando se creó el token.
• nbf — No antes de: segundos Unix antes de los cuales el token no es válido.
• jti — ID JWT: un identificador único para el seguimiento de revocaciones.

Más allá del conjunto estándar, las aplicaciones añaden sus propios claims: role, email, tenant_id, permissions, etc. RFC 7519 no restringe el aspecto de los claims personalizados, aunque IANA mantiene un registro de nombres conocidos para evitar colisiones.

Tres clases de claims que vale la pena distinguir: registrados (los siete anteriores, gestionados por IANA), públicos (registrados en IANA o con espacio de nombres bajo un URI para evitar conflictos) y privados (acordados mutuamente entre emisor y consumidor; sin espacio de nombres).

Decodifica e inspecciona todos los claims de un JWT con nuestro decodificador JWT. Muestra los claims estándar por separado e indica el tiempo hasta la expiración respecto a la hora actual de tu máquina.

Espaciado de nombres de claims personalizados — la práctica estándar: cuando una aplicación añade claims personalizados que pueden incorporarse posteriormente en un token compartido entre proveedores, añade como prefijo un URI que tú mismo poseas. Auth0 usa https://yourdomain.com/claims/role; AWS Cognito usa cognito:groups. Los nombres simples como role o permissions son convenientes pero pueden colisionar con futuros claims registrados por IANA y con los convenios de otros proveedores. OpenID Connect especifica ciertos nombres convencionales (email, name, given_name, family_name, picture, locale) que tienen significados estables en todos los proveedores de identidad — estos son seguros de usar tal cual en cualquier flujo compatible con OIDC. Referencia: Registro de Claims de JSON Web Token de IANA.

Ejemplo práctico: validando exp y nbf

Considera un payload JWT {"sub":"42","iat":1716220800,"exp":1716224400,"nbf":1716220800}. El token fue emitido en la marca de tiempo Unix 1716220800 (2024-05-20 16:00:00 UTC), es válido a partir de ese momento y expira en 1716224400 (2024-05-20 17:00:00 UTC) — una vida útil de una hora. Un verificador correcto lee la hora Unix actual, rechaza el token si now ≥ exp (con una pequeña tolerancia opcional, típicamente 30-60 segundos, para absorber la desincronización del reloj entre servicios), y rechaza si now < nbf. RFC 7519 §4.1.4 exige que el procesamiento de exp “DEBE” tener en cuenta la desincronización del reloj pero deja la tolerancia al implementador. Una tolerancia de 60 segundos es el estándar de facto del sector; jose, jsonwebtoken y pyjwt todos usan ventanas configurables de 0-60s.

Por qué importa: las implicaciones de seguridad

La mayoría de los incidentes de seguridad con JWT se originan en omisiones en la validación de claims, no en fallos criptográficos. El aviso Auth0 CVE-2018-0114 de 2018 documentó bibliotecas que verificaban la firma pero omitían exp, permitiendo la reproducción de tokens robados indefinidamente. Varios frameworks han incluido verificadores predeterminados que ignoran aud, permitiendo que un token acuñado para un servicio sea aceptado por otro en el mismo dominio de confianza. Mejores prácticas: siempre verificar el conjunto completo de claims estándar que aplican (iss, aud, exp, nbf, más la firma y la lista de algoritmos permitidos) — cada biblioteca expone estos como opciones de constructor o de llamada de verificación, y el costo de habilitarlos es esencialmente nulo. Referencia: RFC 8725 — Mejores prácticas actuales para JSON Web Token.