Header (JWT/JWS)

El header de un JWT (o JWS) es el primer segmento separado por puntos, un objeto JSON codificado en base64url que describe las propiedades de firma del token. Decodifícalo y obtendrás un pequeño objeto JSON que típicamente contiene entre 2 y 5 campos.

Campos estándar del header (RFC 7515 §4):

• alg — algoritmo. Requerido. Ej.: HS256, RS256, ES256 o none.
• typ — tipo. Convencionalmente "JWT" cuando el payload es un conjunto de claims JWT.
• kid — ID de clave. Permite al receptor elegir la clave correcta de un conjunto cuando el emisor rota claves.
• jwk / jku — JSON Web Key incrustada o URL a una. Menos común; sensible a la seguridad si se utiliza.
• cty — tipo de contenido. Se usa cuando el payload es una estructura JOSE anidada (p. ej., un JWE dentro de un JWS).

Ejemplo práctico. Un header que se decodifica a:

{ "alg": "RS256", "typ": "JWT", "kid": "2024-q1-key" }

declara que el token está firmado con RS256 (RSA + SHA-256), es un JWT (por lo que el payload es un conjunto de claims) y fue firmado con la clave identificada por 2024-q1-key en el directorio de claves del emisor.

Nota de seguridad crítica: nunca confíes solo en el campo alg. Verifica que el algoritmo coincida con para qué es adecuada tu clave. El ataque de confusión de alg funciona pasando un token firmado con HS256 (HMAC) usando tu clave pública RSA como secreto HMAC: si tu verificador confía ciegamente en alg, acepta la falsificación.

La codificación base64url compacta del header lo hace inspeccionable por humanos: pegar el primer segmento separado por puntos de cualquier JWT en un decodificador base64url revela el algoritmo y la referencia de clave en segundos. Este es el punto de entrada de toda sesión de depuración de JWT: si el header se decodifica como texto ininteligible, el token está mal formado; si se decodifica como un objeto JSON que no reconoces, el emisor cambió algo.

Cuándo y por qué importa

El header JWT importa cada vez que un servicio verifica un token. La cadena de CVE clásica: un verificador acepta el campo alg al pie de la letra y deja pasar un token que especifica "alg": "none" sin ninguna verificación de firma. Este bug llegó a bibliotecas de producción tan recientemente como 2015 (CVE-2015-9235, que afectó a node-jsonwebtoken de Auth0). La defensa es hacer cumplir, en la llamada de verificación, el algoritmo exacto que la biblioteca debe aceptar, por ejemplo, jwt.verify(token, key, { algorithms: ['RS256'] }), y nunca confiar en el header para elegir el algoritmo. Una segunda clase de bug, el ataque de confusión de alg, explota bibliotecas que seleccionan automáticamente HMAC vs RSA según el header: el atacante entrega al verificador un token que afirma ser HS256 pero lo firma con la clave pública RSA (que está publicada) usada como secreto HMAC. El verificador valida contra la clave pública y acepta la falsificación. Ambos bugs son problemas de confianza en el header. Para nuevas integraciones JWT, audita la llamada de verificación y comprueba que fija el algoritmo. Referencia: OWASP — Hoja de trucos de JSON Web Token.

El campo kid en la rotación de claves en producción: en cualquier sistema del mundo real que emita tokens a escala, la clave de firma necesita rotarse periódicamente: cada 90 días es una política común. El campo kid permite al emisor publicar múltiples claves simultáneamente (claves antiguas para tokens en vuelo, claves nuevas para emisiones recientes) y el verificador elige la correcta de un endpoint JWKS. El patrón de rotación estándar: anunciar la nueva clave en el JWKS mientras aún se firma con la antigua, esperar una vida útil de token, cambiar la emisión a la nueva clave, esperar otra vida útil, luego eliminar la clave antigua del JWKS. El campo kid es lo que hace esto gradual: sin él, la rotación de claves requiere un cambio sincronizado en un día determinado.

Cómo se ve el vector de ataque jku / x5u: algunas implementaciones permiten que el header apunte a una URL arbitraria donde supuestamente reside la clave de verificación. Un atacante que establece jku a una URL que controla puede presentar cualquier clave que desee y el verificador la usará. La guía moderna (RFC 8725, mejores prácticas JOSE) es rechazar jku/x5u por completo o hacer cumplir una lista de permitidos de URLs de confianza. Las nuevas integraciones JWT no deben depender de la ubicación de clave controlada por el header. Referencia: RFC 8725 — Mejores prácticas actuales para JSON Web Token.