JWT, JWS, JWE y JOSE en Profundidad

Criptografía, contexto y gobernanza para tokens seguros

Principio central

La firma protege la integridad y el origen; el cifrado protege la lectura. Ninguno de ellos reemplaza la validación de issuer, audience y propósito.

Edición en profundidad: material de estudio y consulta profesional.

radio_button_unchecked Presentación del capítulo

El capítulo anterior presentó OpenID Connect y mostró que los tokens de identificación, access tokens , tokens de cierre de sesión y otros artefactos pueden usar JSON Web Token como formato. Sin embargo, reconocer tres segmentos separados por puntos no es suficiente para intercambiar tokens de forma segura. Es necesario comprender la familia JOSE , la diferencia entre claims y protección criptográfica, la selección de algoritmos, la distribución de claves y las validaciones específicas para cada perfil.

JWT es un marco para el transporte de claims . JWS protege el contenido con una firma digital o un código de autenticación de mensajes. JWE protege la confidencialidad mediante cifrado autenticado. JWK representa una clave en JSON ; un JWKS publica conjuntos de claves; JWA registra algoritmos e identificadores. Estos componentes se combinan, pero no son sinónimos. Un JWT puede ser un JWS , un JWE o una estructura anidada.

En las API empresariales, los errores más graves rara vez se producen en la decodificación de Base64url . Surgen cuando el consumidor acepta algoritmos imprevistos, elige claves utilizando datos que no son de confianza, ignora al issuer o la audience, mezcla ID token y access token , reutiliza la misma regla para diferentes tipos de JWT o mantiene la rotación de claves incompatible con las cachés y la vida útil del token .

Este capítulo profundiza en serializaciones compactas y JSON , headers protegidos, claims , JWK , JWKS , thumbprints, rotación, JWE , tokens anidados y perfiles de access tokens . También incorpora las mejores prácticas de RFC 8725 y la actualización de RFC 9864 sobre identificadores de algoritmos completamente especificados, además de relacionar los conceptos con Axway API Gateway , Azure API Management y bibliotecas de validación.

Cómo estudiar este capítulo

Para cada ejemplo, responda en orden: cuál es el tipo de objeto, quién lo emitió, quién es el destinatario, qué algoritmo está permitido, de dónde proviene la clave, qué bytes se protegieron y qué claims deben validarse. Esta secuencia reduce la posibilidad de aceptar un token solo porque su firma parece válida.

Objetivos de aprendizaje

• Distinguir JOSE , JWT , JWS , JWE , JWK , JWKS y JWA .
• Explique Base64url , UTF-8 , JSON y el impacto de la representación exacta de bytes.
• Interpretar claims registradas, públicas y privadas sin confundir presencia con confianza.
• Describir la serialización compacta JWS y la serialización JSON .
• Diferenciar firma digital y MAC, incluidas las implicaciones de no repudio y distribución de claves.
• Restrinja los algoritmos por lista de permitidos y evite la confusión de algoritmos.
• Utilice typ , cty , kid y crit de forma segura y contextual.
• Interprete los JWK RSA , EC, OKP y oct y separe el material público del privado.
• Planifique JWKS , cache , rotación, transferencia y eliminación de claves.
• Explique los parámetros alg y enc en JWE y la estructura de cinco partes.
• Diseñe tokens anidados y decida cuándo firmar, cifrar o utilizar ambos.
• Valide los JWT de forma criptográfica, temporal y semántica.
• Aplique el perfil JWT para acceder a tokens y distinguir otros tipos de JWT .
• Diagnostique fallas de firma, audience, issuer, kid , caché, reloj y cifrado.

Estructura del capítulo

• 18.1 La familia JOSE y sus responsabilidades
• 18.2 Base64url , UTF-8 y JSON canónico
• 18.3 JWT : claims y sobre de seguridad
• 18.4 Claims registradas, públicas y privadas
• 18.5 JWS : signing input y serializaciones
• 18.6 Firma digital y MAC
• 18.7 Algoritmos, allowlists y RFC 9864
• 18.8 Headers typ , cty , kid y crit
• 18.9 JWK : anatomía y tipos clave
• 18.10 JWKS y distribución de claves
• 18.11 kid , thumbprints y certificados X.509
• 18.12 Rotación, cache y retirada de claves
• 18.13 JWE : alg , enc y Content Encryption Key
• 18.14 Serializaciones de JWE y destinatarios múltiples
• 18.15 JWT anidado y orden de protecciones
• 18.16 Pipeline de validación segura
• 18.17 Perfil JWT para access tokens OAuth 2.0
• 18.18 Otros perfiles JWT
• 18.19 Proof-of-possession y claim cnf
• 18.20 Aplicación en API Gateways , Axway y Azure
• 18.21 Amenazas y hardening
• 18.22 Privacidad, logging y minimización
• 18.23 Troubleshooting
• 18.24 Estudios de casos y laboratorios
• Resumen, lista de verificación, ejercicios, glosario y referencias.

radio_button_unchecked 18.1 La familia JOSE y sus responsabilidades

JSON Object Signing and Encryption es el conjunto de especificaciones que definen estructuras JSON para firma, autenticación, cifrado y representación de claves. El objetivo es transportar objetos de seguridad de forma que sea compatible con HTTP , URI y aplicaciones que ya utilizan JSON . La familia se dividió en documentos para separar la estructura, los algoritmos, las claves y la semántica de las claims .

JWT define un conjunto de claims y reglas de procesamiento. JWS define cómo proteger una secuencia de bytes con una firma digital o MAC. JWE define cifrado autenticado y gestión de claves de contenido. JWK define cómo representar claves criptográficas en JSON , mientras que JWA asocia identificadores como RS256, ES256 o A256GCM con operaciones concretas.

Un token comercialmente llamado JWT suele ser un JWS en serialización compacta, pero esta es una convención frecuente, no una equivalencia formal. También hay JWT cifrados como JWE , JWS cuya carga útil no es un JWT y objetos JOSE con múltiples firmas o destinatarios que utilizan la serialización JSON .

radio_button_unchecked 18.2 Representación Base64url , UTF-8 y JSON

Base64url transforma bytes en caracteres seguros para URL reemplazando los caracteres + y / y normalmente eliminando el relleno =. La operación no cifra, no comprime y no proporciona integridad. Cualquiera que reciba un JWS compacto puede decodificar el encabezado y la carga útil, incluso si no tiene la clave de firma.

Antes de codificar, los objetos JSON se convierten a bytes UTF-8 . Los espacios, el orden de los miembros, los escapes y las formas numéricas pueden producir diferentes secuencias de bytes incluso cuando dos representaciones parecen semánticamente equivalentes. En JWS , la firma cubre la representación exacta utilizada en la entrada de firma; una biblioteca no debe decodificar la carga útil y volver a serializarla para verificar la firma.

JSON permite una flexibilidad que requiere validación defensiva. Los nombres de miembros duplicados, los números fuera del rango esperado, las cadenas con normalización diferente y las representaciones múltiples pueden provocar interpretaciones diferentes entre bibliotecas. El perfil que utiliza JWT debe definir claims , tipos y límites aceptados, rechazando objetos ambiguos.

Exemplo conceitual - transformação do header
header JSON: {"alg":"RS256","typ":"JWT","kid":"key-2026-07"}
BASE64URL(UTF8(header))
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0yMDI2LTA3In0
Base64url e apenas codificacao. O conteudo permanece legivel.

Error recurrente

Ocultar un token en el navegador, en un encabezado o en un registro no equivale a proteger la confidencialidad. Un JWS firmado sigue siendo legible. Para evitar que se lea el contenido, se requiere JWE u otro canal adecuado y protección de almacenamiento.

radio_button_unchecked 18.3 JWT : claims y sobre de seguridad

Una claim es una afirmación representada por un par nombre-valor. El conjunto de claims JWT es un objeto JSON que reúne estas claims . El formato no determina automáticamente quién puede emitir la claim , cuánto tiempo es válida o cómo debe interpretarse. Estas reglas pertenecen al perfil y a la relación de confianza entre issuer y destinatario.

JWT puede estar protegido por JWS o JWE . En un JWS , las claims son legibles, pero los cambios se pueden detectar cuando la firma se verifica correctamente. En un JWE , el contenido está cifrado y autenticado. En ambos casos, el destinatario aún necesita validar las reglas específicas del issuer, la audience, la hora, el tipo y la aplicación.

Las claims no deben llevar un estado arbitrario solo porque el token admite JSON . Los tokens grandes aumentan el uso del ancho de banda, el tamaño del encabezado, la presión sobre los proxy y el riesgo de exposición. La emisión debe priorizar datos estables necesarios para la decisión, utilizando identificadores de información que deba ser consultada en tiempo real.

radio_button_unchecked 18.4 Claims registradas, públicas y privadas

Los claims registrados tienen nombres y semántica documentados en el registro de la IANA , como iss, sub, aud, exp y jti. No son obligatorios en todos los JWT , pero perfiles como OIDC y RFC 9068 especifican cuáles deben aparecer. El uso correcto depende de respetar el tipo JSON previsto y el propósito del perfil.

Los claims públicos utilizan nombres resistentes a colisiones, generalmente registrados o basados en un URI controlado por la organización. Los claims privados son acuerdos locales entre el issuer y el consumidor, como roles, teniente_id o límite_transacción. Son útiles, pero pueden chocar entre ecosistemas y cambiar de significado cuando un token cruza los límites organizacionales.

Una claim de autorización no debe aceptarse simplemente porque existe. El resource server necesita conocer el issuer, el perfil, el espacio de nombres, el tipo y la política que la produce. Por ejemplo, los roles emitidos por un directorio pueden representar grupos administrativos en lugar de permisos de dominio. La aplicación debe transformar claims confiables en decisiones locales explícitas.

Diseño de claims

Prefiere nombres estables, tipos simples y significado documentado. Evite incluir secretos, datos personales innecesarios, listas enormes de grupos u objetos comerciales que cambien durante la validez del token .

radio_button_unchecked 18.5 JWS : signing input y serializaciones

JWS Compact Serialization tiene tres partes: encabezado protegido, carga útil y firma. Los dos primeros están codificados en Base64url y unidos por un punto para formar la entrada de firma. El algoritmo utiliza este valor y la clave adecuada para producir la tercera parte. La verificación reconstruye los mismos bytes y valida la operación criptográfica.

La serialización JWS JSON representa el objeto como JSON y permite múltiples firmas en la misma carga útil. La forma aplanada contiene una firma; la forma general contiene una colección. Este modelo es útil cuando diferentes organizaciones o claves necesitan firmar el mismo contenido, aunque aumenta la complejidad de las políticas y el procesamiento.

RFC 7797 permite cargas útiles no codificadas en Base64url a través del parámetro b64 en el encabezado protegido y el uso de crit . Esta opción es especializada y puede mejorar la integración con contenido resaltado, pero requiere soporte explícito y cuidado de los caracteres que interfieren con la serialización compacta. Las API comunes deberían preferir el comportamiento predeterminado que ofrecen las bibliotecas maduras.

Pseudocódigo - construção conceitual de um JWS
protected = BASE64URL(UTF8({"alg":"ES256","kid":"ec-1"}))
payload   = BASE64URL(payload_bytes)
signing_input = protected + "." + payload
signature = ECDSA_sign(private_key, signing_input)
jws_compact = protected + "." + payload + "." + BASE64URL(signature)

radio_button_unchecked 18.6 Firma digital y MAC

Los algoritmos asimétricos utilizan una clave privada para firmar y una clave pública para verificar. El issuer mantiene bajo control la clave privada y distribuye únicamente material público. Este modelo facilita la validación por múltiples API y reduce la capacidad de los validadores para emitir tokens , ya que tener la clave pública no permite crear nuevas firmas.

Los algoritmos MAC como HMAC utilizan el mismo secreto para producir y verificar código. Cada componente capaz de validar también puede generar un token indistinguible. En arquitecturas con muchos servidores de recursos, el intercambio de secretos aumenta el impacto del compromiso y dificulta la asignación de qué componente produjo un token .

La firma digital no crea automáticamente un no repudio legal. Se requieren registros, control de claves, certificación, políticas, auditorías y contexto. Asimismo, verificar la firma sólo prueba que los bytes corresponden a una clave aceptada; no prueba que el token esté vigente, destinado a esa API o autorizado para la operación.

radio_button_unchecked 18.7 Algoritmos, allowlists y RFC 9864

El encabezado alg declara el algoritmo utilizado, pero no debe controlar por sí solo la decisión. El consumidor debe tener una lista de permitidos configurada por perfil, issuer y token type. Si la aplicación acepta cualquier algoritmo anunciado, puede producirse confusión, degradación del algoritmo o uso de una clave operativa incompatible.

Es necesario evaluar los algoritmos para determinar el conjunto completo de parámetros, tamaño de clave, biblioteca, requisitos reglamentarios e interoperabilidad. RS256 sigue siendo ampliamente compatible; PS256 utiliza RSA -PSS; ES256 utiliza ECDSA con P-256 y SHA-256 . Los algoritmos modernos basados en EdDSA deben considerar actualizaciones de identificadores completamente especificados y soporte real del ecosistema.

RFC 9864, publicado en 2025, diferencia los algoritmos completamente especificados de aquellos que dependen de parámetros externos para determinar el funcionamiento. Actualiza los registros JOSE y desaprueba los identificadores polimórficos en situaciones cubiertas por la especificación. Las nuevas arquitecturas deben consultar el registro actual de la IANA y evitar negociar nombres ambiguos sólo por compatibilidad histórica.

regla de seguridad

Configure el algoritmo esperado junto al issuer y el token type. No derive la lista de permitidos del propio encabezado alg y no reutilice la misma clave en familias de algoritmos incompatibles.

radio_button_unchecked 18.8 Headers typ , cty , kid y crit

El parámetro de tipo declara el tipo de objeto para la aplicación. No cambia el cifrado, pero ayuda a evitar confusión entre JWT con diferentes propósitos. RFC 8725 recomienda tipificación explícita y reglas mutuamente excluyentes. El perfil del access token RFC 9068 utiliza at+ jwt , mientras que los tokens de identificación suelen utilizar JWT o dependen del contexto OIDC .

cty describe el tipo de carga útil, siendo especialmente útil en objetos anidados. Un JWE que contiene un JWT firmado puede usar cty igual a JWT . kid es un consejo para seleccionar una clave entre varias; no es un identificador global, no prueba la propiedad y puede repetirse entre issuers.

crit enumera los parámetros del header que deben entenderse para procesar el objeto. Si se desconoce un parámetro crítico, el consumidor debe rechazar el token . Ignorar crit destruye la capacidad de las extensiones para modificar la semántica de seguridad. Los headers que influyen en la operación criptográfica deben estar en el protected header , no solo en campos desprotegidos de la serialización JSON .

radio_button_unchecked 18.9 JWK : anatomía y tipos clave

La clave web JSON representa material criptográfico con parámetros definidos por kty. Una clave RSA pública incluye n y e; una clave EC incluye crv, xey; una clave OKP incluye curva y coordenada pública; una clave simétrica oct incluye k. Los parámetros privados como d, p, q o k no deberían aparecer en JWKS públicos.

uso indica un propósito amplio, como sig o enc . key_ops enumera operaciones específicas, como verificar, firmar, cifrar o descifrar. alg puede restringir la asociación con un algoritmo. Estos campos deben ser coherentes entre sí y con la política de aplicación; no deberían ampliar automáticamente lo que la clave puede hacer.

Las claves deben tener origen, titular, fecha de activación, fecha de retiro, finalidad y procedimiento de revocación. Representar una clave en JSON no elimina los controles secretos. Las claves privadas deben permanecer en HSM , KMS , bóveda o almacenamiento seguro y cargarse únicamente mediante procesos autorizados.

Exemplo - JWK pública RSA
{
  "kty": "RSA",
  "kid": "signing-2026-07",
  "use": "sig",
  "alg": "RS256",
  "n": "sXch...base64url-modulus...",
  "e": "AQAB"
}

material privado

Un JWKS público debe contener únicamente parámetros públicos. La presencia de d, p, q, dp, dq, qi o k puede exponer una clave privada o un secreto simétrico y requiere una respuesta inmediata al incidente.

radio_button_unchecked 18.10 JWKS y distribución de claves

Un conjunto de claves web JSON contiene la propiedad de claves con una lista de JWK . Los proveedores de identidades publican JWKS para que los clientes y servidores de recursos verifiquen las firmas. El endpoint debe obtenerse mediante una configuración confiable o metadata vinculados al issuer, nunca mediante una URL arbitraria proporcionada por el token .

El consumidor mantiene el caché para evitar la dependencia de la red en cada solicitud. La caché debe respetar las políticas HTTP , tener un límite de tamaño, tiempo de espera, actualización controlada y respaldo seguro. En caso de una falla temporal del terminal, las claves conocidas pueden seguir siendo válidas según la política, pero los tokens sin clave no deben aceptarse solo para preservar la disponibilidad.

La validación primero debe corregir el issuer permitido, encontrar el conjunto correspondiente y luego usar kid , kty, alg y key_ops para filtrar candidatos. Un caché global indexado solo por kid permite colisiones entre tenants y issuers. El índice seguro incluye al menos el issuer y el identificador de clave.

radio_button_unchecked 18.11 kid , thumbprints y certificados X.509

kid es un identificador elegido por el issuer y puede ser una cadena opaca. Facilita la rotación, pero no tiene unicidad global. JWK Thumbprint, definido por RFC 7638, calcula un resumen sobre una representación canónica de los miembros requeridos de la clave y produce un identificador derivado del propio material público.

x5c puede transportar una cadena de certificados X.509 ; x5t y x5t#S256 llevan thumbprints de certificados. Cuando se utilizan certificados, el consumidor debe validar la cadena, el uso de claves, la validez y la confianza según el perfil. Comparar solo un thumbprint recibido en el token no crea un ancla confiable.

jku y x5u apuntan a recursos remotos. Seguir estas URL sin lista de permitidos crea SSRF , acceso a redes internas y transferencia de claves. En las plataformas empresariales, los endpoints de metadata y JWKS deben estar preconfigurados y resueltos a través de canales controlados y monitoreados.

Pseudocódigo - JWK Thumbprint
thumbprint_input = canonical_json({
  "e": "AQAB",
  "kty": "RSA",
  "n": "sXch..."
})
jwk_thumbprint = BASE64URL(SHA256(UTF8(thumbprint_input)))

radio_button_unchecked 18.12 Rotación, cache y retirada de claves

La rotación planificada comienza con la publicación anticipada de la nueva clave. Una vez que los cachés han tenido la oportunidad de actualizarlo, el issuer comienza a firmar nuevos tokens con el nuevo kid . La clave anterior permanece publicada hasta que todos los tokens firmados por ella hayan caducado, además de las tolerancias de reloj, las colas, los reintentos y el retraso de propagación.

Quitar la clave inmediatamente después de cambiar el firmante hace que fallen los tokens que aún son válidos. Mantener las claves indefinidamente reduce la capacidad de revocación y amplía la superficie. La ventana debe calcularse en función de la vida útil máxima del token , la actualización, el Cache -Control, los tiempos de actualización y el comportamiento de los componentes desconectados.

Cuando aparece un kid desconocido, el validador puede actualizar el JWKS una vez dentro de los límites y utilizar la fusión para evitar múltiples búsquedas simultáneas. Los tokens aleatorios no deberían generar una solicitud por intento. La limitación de velocidad, la caché negativa corta y el disyuntor protegen el endpoint de metadata y la propia API Gateway .

En caso de compromiso clave, la prioridad puede requerir el retiro inmediato y la invalidación de los tokens , aceptando una indisponibilidad controlada. El plan debe definir la detección, rotación de emergencia, comunicación a los consumidores, revocación, análisis de emisión indebida y restablecimiento de la confianza.

Ecuación operativa

El tiempo mínimo de superposición debe considerar: vida máxima del token + tolerancia del reloj + retraso de la caché + colas y reintentos. Utilice métricas reales, no solo el valor de experiencia nominal.

radio_button_unchecked 18.13 JWE : alg , enc y Content Encryption Key

JWE utiliza una Content Encryption Key, o CEK , para cifrar plaintext con el algoritmo de cifrado autenticado indicado por enc . El parámetro alg define cómo se protege, transporta, deriva o comparte esta CEK con el destinatario. Por lo tanto, alg y enc tienen responsabilidades diferentes y ambas deben estar permitidas por la política.

En RSA -OAEP-256, la CEK se cifra con la clave pública RSA del destinatario. En dir, la clave simétrica compartida se utiliza directamente como CEK . En ECDH-ES, una operación de acuerdo de claves deriva material de claves elípticas. La elección cambia la distribución de claves, el secreto directo, la interoperabilidad y el riesgo de compromiso.

Algoritmos como el A256GCM brindan confidencialidad e integridad en una única operación autenticada. IV o nonce deben cumplir con los requisitos del algoritmo y no pueden reutilizarse bajo la misma clave cuando esto comprometa la seguridad. La etiqueta de autenticación debe validarse antes de publicar cualquier texto sin formato en la aplicación.

El cifrado no elimina la necesidad de una firma cuando el destinatario necesita verificar la autoría por separado. Un JWE demuestra que la etiqueta es válida según la clave de cifrado, pero la identidad del productor depende del mecanismo de gestión de claves y del perfil. Los tokens anidados pueden combinar firma y cifrado.

radio_button_unchecked 18.14 Serializaciones de JWE y destinatarios múltiples

La serialización compacta tiene cinco partes: encabezado protegido, clave cifrada, IV, texto cifrado y etiqueta de autenticación. Es adecuado para un destinatario y transporte en parámetros o headers . La serialización JSON permite campos protegidos y desprotegidos, datos autenticados adicionales y múltiples destinatarios, cada uno con su propia clave cifrada.

Entre varios destinatarios, se puede compartir el mismo texto cifrado mientras que la CEK está protegida por separado para cada clave. Esto reduce la duplicación, pero crea una política más compleja: todos los destinatarios reciben el mismo contenido y deben ser gobernados como un todo. Para eliminar un destinatario es necesario volver a cifrarlo para mensajes futuros.

Los headers desprotegidos se pueden cambiar sin invalidar la etiqueta cuando no participan en AAD . La información que determina el algoritmo, clave, tipo o interpretación debe estar en el encabezado protegido. El consumidor necesita saber qué campos están autenticados y rechazar combinaciones inconsistentes.

Mapa da JWE Compact Serialization
protected.encrypted_key.iv.ciphertext.tag
1. protected: alg, enc, kid, cty
2. encrypted_key: CEK protegida para el destinatario
3. iv: valor único exigido por el algoritmo
4. ciphertext: plaintext cifrado
5. tag: autenticidad del ciphertext y de los datos asociados

radio_button_unchecked 18.15 JWT anidado y orden de protecciones

Un JWT anidado aplica JWS y JWE en secuencia. El patrón común es firmar primero y cifrar después. El issuer crea un JWS que preserva la integridad y la autoría, luego utiliza ese JWS como texto sin formato de un JWE destinado al consumidor. El JWE externo usa cty igual que JWT para indicar contenido anidado.

Después del descifrado, el destinatario aún necesita validar el JWS interno. La validez de la etiqueta externa no reemplaza la firma, el issuer, la audience o la hora del token interno. Asimismo, la firma interna no prueba que el objeto externo estuviera destinado al componente que lo recibió.

Cifrar y luego firmar expone los metadata y la firma externa, y produce una semántica diferente. Los perfiles deben definir el orden, los algoritmos, los tipos y el manejo de errores. No invente su propia composición cuando un perfil estandarizado o un canal TLS firmado por token cumpla con el requisito.

radio_button_unchecked 18.16 Pipeline de validación segura

El validador comienza con el contexto externo: endpoint , issuer esperado, token type y perfil. Luego realiza un análisis defensivo con límites de tamaño, número de segmentos, profundidad de JSON y tipos. El encabezado que no es de confianza solo se lee para seleccionar una operación permitida dentro de la configuración.

La selección de claves se produce en el conjunto asociado al issuer. alg debe estar en la lista de permitidos y ser compatible con kty, use y key_ops. La firma, MAC o etiqueta está completamente verificada. Las fallas criptográficas finalizan el procesamiento sin probar algoritmos alternativos no autorizados.

Después del cifrado vienen las validaciones semánticas: iss, aud, exp, nbf, iat, typ , cty , nonce , jti, scopes , tenants y claims de perfil. Las reglas para el access token , el ID token , la aserción del cliente y el token de cierre de sesión deben ser mutuamente excluyentes. Aceptar un token en múltiples contextos favorece la confusión entre JWT .

Finalmente, la autorización aplica las reglas locales. Un token válido no implica permiso para ningún objeto. El backend debe verificar la operación, los recursos, la propiedad, el contexto empresarial y las políticas actuales. Los registros deben registrar resultados e identificadores mínimos, nunca el token completo.

radio_button_unchecked 18.17 Perfil JWT para access tokens OAuth 2.0

RFC 9068 define un perfil interoperable para access tokens JWT . No obliga a OAuth a utilizar JWT ; Los access tokens aún pueden ser opacos. Cuando se adopta el perfil, el token debe estar firmado, no puede usar alg none y debe declarar un tipo igual a at+ jwt , además de claims y reglas específicas para issuer, asunto, audience, hora, client_id y autorización.

El resource server valida el token para su propia audience. Los scopes pueden aparecer en el scope y se puede incluir información de autorización adicional según el perfil y los acuerdos. Las API de otra audience no deben aceptar el token simplemente porque fue emitido por el mismo authorization server.

Los access tokens JWT reducen las llamadas de introspección y permiten la validación local, pero dificultan la revocación inmediata. La corta vida útil, la rotación, las restricciones del remitente, las listas de emergencia y las políticas de sesión pueden reducir la exposición. Para datos que necesitan reflejar un estado instantáneo, la introspección o la consulta de autorización pueden ser más apropiadas.

Exemplo conceitual - header e claims de access token
{
  "typ": "at+jwt",
  "alg": "RS256",
  "kid": "as-signing-4"
}.
{
  "iss": "https://auth.example",
  "sub": "user-481",
  "aud": "https://api.example/payments",
  "client_id": "mobile-app",
  "scope": "payments.read payments.create",
  "iat": 1784126100,
  "exp": 1784126700,
  "jti": "8b28b730-..."
}

El access token no es un ID token

El access token está destinado al resource server y describe la autoridad. El ID token está destinado al cliente OIDC y describe la autenticación. Aunque ambos son JWT firmados por el mismo issuer, sus reglas no se pueden intercambiar.

radio_button_unchecked 18.18 Otros perfiles JWT

JWT se utiliza en varios perfiles. Los tokens de identificación siguen las reglas de OpenID Connect. Las aserciones de cliente RFC 7523 le permiten autenticar a un cliente en el token endpoint o presentar una concesión. RFC 9101 Los objetos de solicitud protegen los parámetros de autorización. Los tokens de cierre de sesión llevan eventos específicos de la sesión. Las respuestas de introspección se pueden proteger como JWT según RFC 9701.

Cada perfil define tipo, audience, claims obligatorios, tiempo, replay y destinatario. Una biblioteca genérica que sólo comprueba firmas no conoce estas reglas. La aplicación debe seleccionar un validador o una configuración específicos para cada tipo y mantener endpoints separados cuando sea posible.

Siguen surgiendo nuevos formatos. RFC 9901, publicado en 2025, estandariza la divulgación selectiva JWT para permitir la presentación selectiva de claims en escenarios de credenciales. Este mecanismo cuenta con su propio modelo de emisión, presentación, divulgación y vinculación de claves; no debe tratarse como un JWT tradicional sólo porque reutiliza componentes JOSE .

radio_button_unchecked 18.19 Proof-of-possession y claim cnf

Los bearer tokens pueden ser utilizados por cualquier parte que obtenga el valor. Los sender-constrained tokens vinculan el uso a una clave o certificado. La claim cnf confirma qué clave debe demostrarse. El binding puede utilizar el thumbprint de la clave JWK , el thumbprint del certificado o parámetros definidos por el perfil.

En DPoP, el cliente presenta una prueba JWS por solicitud y el access token puede contener jkt, la huella digital de la clave pública. En los access tokens vinculados a mTLS , cnf puede contener x5t#S256 del certificado utilizado en el canal. El resource server verifica tanto el token como la prueba o certificado correspondiente.

La proof-of-possession reduce la replay de tokens robados, pero agrega administración de claves, sincronización, nonces , proxies TLS y diagnósticos. La API Gateway debe preservar o verificar la evidencia en el punto correcto. Terminar mTLS en un componente y reenviar solo un encabezado que no es de confianza al backend destruye el enlace si ese encabezado se puede inyectar externamente.

Exemplos conceituais - confirmação da chave
"cnf": {
  "jkt": "0ZcOCORZNYzC-7hV..."
}
# ou, para certificado mTLS
"cnf": {
  "x5t#S256": "qP3Q...thumbprint..."
}

radio_button_unchecked 18.20 Aplicación en API Gateways , Axway y Azure

API Gateway actúa como un punto de aplicación de políticas y necesita separar la validación del token de autorización de la ruta. Una política sólida corrige el issuer, la audience, los algoritmos, la ubicación de los metadata, las claims obligatorias y el comportamiento de la caché. Los headers derivados de claims deben reemplazar los valores externos y enviarse al backend solo a través de un canal confiable.

En Axway API Gateway , los filtros de validación JWT y las bibliotecas de identidad pueden verificar firmas, claims y certificados. La configuración debe limitar algoritmos, elegir tienda o JWKS por entorno y correlacionar fallas con seguimientos seguros. Las políticas compartidas evitan la divergencia, pero deben permitir diferencias de audience y perfil entre las API .

En Azure API Management, validate- jwt y validate-azure-ad- token integran la validación con la configuración, las audiences y las notificaciones requeridas de OpenID. La política debe verificar el token destinado a la API y no simplemente aceptar cualquier token del tenant. Es necesario considerar la rotación y las cachés de metadata para cambios e incidentes.

Cuando la API Gateway vuelve a emitir un token interno, se produce una nueva relación de confianza. Primero se debe validar el token externo; el token interno debe tener su propio issuer, audience, vida y claims mínimos. El backend confía en el issuer interno, no en el token original, y la correlación debe preservar los identificadores para la auditoría.

Exemplo conceitual - política de validação no gateway
<validate-jwt header-name="Authorization"
              require-scheme="Bearer"
              failed-validation-httpcode="401">
  <openid-config url="https://auth.example/.well-known/openid-configuration" />
  <audiences>
    <audience>https://api.example/payments</audience>
  </audiences>
  <required-claims>
    <claim name="scope" match="all">
      <value>payments.read</value>
    </claim>
  </required-claims>
</validate-jwt>

Propagación de identidad

Elimine los headers de identidad recibidos de Internet antes de crear headers internos. El backend debe aceptar estos valores solo desde la API Gateway autenticada y, para decisiones críticas, continuar aplicando la autorización de dominio.

radio_button_unchecked 18.21 Amenazas y hardening

La confusión de algoritmos ocurre cuando el consumidor permite que alguien seleccione una operación imprevista, como usar una clave pública RSA como secreto HMAC . La defensa es una lista de permitidos fija, claves separadas por uso y una biblioteca actualizada. alg none debe rechazarse en tokens de seguridad, a menos que sea un perfil excepcional y explícitamente aislado.

La sustitución y la cross- JWT confusion ocurren cuando se acepta un token válido en el contexto incorrecto. Un ID Token usado como access token , un token de otra audience, un token de staging en producción y una client assertion aceptada por la API son ejemplos. typ explícito, reglas mutuamente excluyentes, issuer y audience reducen el riesgo.

Los campos jku URL , x5u y jwk controlados por el token pueden inducir SSRF o sustitución de claves. kid puede provocar un recorrido de ruta o una consulta de base de datos insegura cuando se concatena sin validación. El validador debe tratar los headers como entradas hostiles, utilizar endpoints preconfigurados y limitar el tamaño y los caracteres.

El oráculo de compresión es un riesgo cuando los datos secretos y controlados por el atacante se comprimen antes del cifrado y se puede observar el tamaño. RFC 8725 recomienda evitar la compresión de entradas criptográficas en escenarios sensibles. Los tokens también necesitan límites para evitar un consumo excesivo de CPU y memoria.

radio_button_unchecked 18.22 Privacidad, logging y minimización

Un JWS puede contener nombre, correo electrónico, grupos, tenants, identificadores y datos comerciales en texto legible por humanos. El registro del token completo en registros de acceso, seguimientos, APM, herramientas de soporte o mensajes de error replica datos y credenciales en múltiples sistemas. Incluso los tokens caducados pueden revelar información personal o arquitectura interna.

Los registros deben registrar solo los campos necesarios: issuer normalizado, audience esperada, kid , resultado de la validación, código de error, hash no reversible del jti o asunto cuando esté permitido e ID de correlación. El valor sin procesar del header Authorization debe enmascararse antes de llegar a los registros genéricos.

El cifrado JWE reduce la lectura durante el transporte y el almacenamiento, pero el destinatario necesita descifrado y puede filtrar el texto sin formato en los registros. La minimización sigue siendo el control más eficiente. Las declaraciones de autorización también pueden revelar la estructura organizacional; evaluar la necesidad, la retención y el acceso.

Regla de observabilidad

Recopile evidencia suficiente para diagnosticar sin copiar credenciales. Nunca publique tokens reales en tickets, chats, documentación o herramientas de descifrado en línea.

radio_button_unchecked 18.23 Troubleshooting basada en evidencia

El diagnóstico comienza con la clasificación de la avería. El error de análisis indica estructura, Base64url o JSON . La firma no válida apunta a clave, algoritmo, bytes, entorno o corrupción. Un kid desconocido sugiere una rotación, un caché o un issuer incorrectos. La audience no válida y el issuer no válido son fallas semánticas, no criptográficas.

Compare el token con los metadata del issuer sin exponer el valor completo. Registre alg , kid , typ , iss, aud, exp y hora local. Consulte el JWKS confiable y confirme kty, uso, key_ops y alg . Compruebe si la nueva clave ya está publicada y si la anterior aún debería permanecer. En clústeres, compare cachés y relojes entre instancias.

Para JWE , separe el error de la gestión de claves, el descifrado y la etiqueta. Una clave privada incorrecta, un algoritmo incompatible, un IV no válido y un texto cifrado modificado producen diferentes síntomas en la biblioteca, pero la respuesta externa debe ser genérica para no crear Oracle. Conserve los detalles solo en registros restringidos.

En las API Gateways , correlacione el registro de acceso, el seguimiento de políticas, las métricas de metadata, el caché y el backend . La API Gateway , la API u otro proxy pueden generar una respuesta 401. Identifique el componente exacto y el paso que falló antes de cambiar la configuración.

radio_button_unchecked 18.24 Estudios de casos y laboratorios

Caso 1: Rotación intermitente: algunas instancias aceptan el nuevo chico y otras devuelven 401. La investigación muestra cachés locales con diferentes tiempos y se actualizan sin fusionarse. La solución publica la clave con anticipación, estandariza el cache , agrega actualización controlada y mantiene la clave anterior para su máxima validez.

Caso 2: token válido para una audience incorrecta: la API Gateway verifica la firma de un token emitido al portal y reenvía la llamada a la API . La solución requiere tipo de API y audience, separa los validadores de ID token y de access token y agrega pruebas negativas a la canalización.

Caso 3: URL clave por token : una biblioteca sigue a jku y permite al atacante proporcionar su propia clave. La solución elimina la resolución dinámica, corrige los metadata por issuer, bloquea las salidas innecesarias y revisa los tokens ya aceptados.

Caso 4: claims confidenciales en registros: un incidente revela que APM almacenó la autorización completa. La solución enmascara el encabezado en el primer punto de entrada, reduce las claims emitidas, aplica retención y revoca tokens potencialmente expuestos.

Laboratorio 1: validar un JWS con la biblioteca local

• Generar un par de claves de laboratorio en un entorno aislado y autorizado.
• Emita un JWS de corta duración con iss, aud, exp, typ y kid .
• Valide con la lista de permitidos de algoritmos y la clave pública preconfigurada.
• Cambie un byte de la carga útil y observe la falla criptográfica.
• Cambie aud sin volver a firmar para comparar el error de firma y el error semántico.

Laboratorio 2: simular la rotación de JWKS

• Publica K1 y emite tokens con el kid K1.
• Agregue K2 al conjunto antes de usarlo para firmar.
• Actualice el firmante a K2 y mantenga K1 disponible.
• Observe el comportamiento de la caché en diferentes instancias.
• Elimine K1 solo después de que expiren los tokens y el margen operativo.

Laboratorio 3 - pruebas negativas obligatorias

• Rechazar alg none y algoritmo fuera de la lista de permitidos.
• Rechazar issuer, audience y tipo incorrectos.
• Rechazar token vencido, futuro o excesivamente grande.
• Rechace a un kid desconocido sin activar una actualización ilimitada.
• Rechaza críticos desconocidos y headers remotos no autorizados.
• Rechazar el token de ID presentado a la API como un access token .

Seguridad del laboratorio

Utilice únicamente claves y tokens ficticios. Nunca copie credenciales de producción en herramientas de prueba, sitios de descifrado o documentos de capacitación.

radio_button_unchecked Resumen del capítulo

JOSE separa claims , firma, cifrado, algoritmos y representación de claves. JWT no significa automáticamente token firmado, access token o credencial segura. La confianza surge de la combinación de estructura válida, funcionamiento criptográfico correcto, clave vinculada a un issuer permitido y validación semántica del perfil.

JWS protege la integridad y el origen, pero mantiene la carga útil legible. JWE protege la confidencialidad mediante cifrado autenticado y separa alg , responsable de CEK , de enc , responsable del contenido. Los tokens anidados pueden combinar propiedades, pero aumentan la complejidad y necesitan un perfil claro.

JWKS y la rotación son parte del runtime. La publicación temprana, el cache controlado, la superposición y el retiro planificado evitan el tiempo de inactividad. kid es sólo una pista dentro del issuer; Las URL y claves proporcionadas por el propio token no deberían generar confianza.

RFC 8725 orienta allowlists, validaciones mutuamente excluyentes, tipado explícito y protección contra mix-up. RFC 9864 actualiza el tratamiento de algoritmos completamente especificados y el registro de IANA sigue siendo la referencia operativa para nombres y estados.

Lista de verificación de diseño y operación.

• ¿Existe un perfil documentado para cada tipo de JWT admitido?
• ¿El issuer, la audience, el tipo y los algoritmos están definidos por la configuración de confianza?
• ¿La validación utiliza la clave de issuer correcta y no un caché global por kid ?
• ¿ JWKS tiene caché, límites, actualización combinada y rotación probada?
• ¿Las claves privadas se almacenan en un HSM , KMS o una bóveda auditada?
• ¿Los algoritmos son compatibles con kty, use y key_ops?
• ¿Las claims temporales utilizan UTC, sincronización de reloj y tolerancia limitada?
• ¿Los tokens de identificación, access tokens , aserciones de clientes y tokens de cierre de sesión utilizan validadores separados?
• ¿Los headers jku, x5u, jwk y crit reciben un tratamiento seguro?
• ¿Los registros enmascaran la autorización y no almacenan tokens completos?
• ¿Las pruebas negativas cubren la confusión de tipo, audience, algoritmo y rotación?
• ¿Existe un procedimiento para comprometer y retirar la llave de emergencia?

radio_button_unchecked Ejercicios de repaso

• Explique por qué un JWT descodificado con éxito sigue siendo poco fiable.
• Describe la diferencia entre JWT , JWS y JWE usando un ejemplo de API .
• Calcule qué componentes pueden emitir tokens cuando HS256 se comparte entre cinco API .
• Proponer una secuencia de rotación para tokens con vencimiento de 20 minutos y caché JWKS de 10 minutos.
• Explique por qué el kid no puede identificar una clave globalmente.
• Diferenciar alg y enc en un JWE con RSA -OAEP-256 y A256GCM.
• Describa cómo typ ayuda a evitar el uso de ID Token como access token .
• Explique el riesgo de seguir a jku informado por el token .
• Compare el token JWT validado localmente y el token opaco con introspección.
• Defina qué información se puede registrar en los registros sin copiar la credencial.

radio_button_unchecked Glosario

radio_button_unchecked Anexo A - Matriz de decisión

radio_button_unchecked Referencias técnicas

• IETF . RFC 7515: Firma web JSON ( JWS ). 2015.
• IETF . RFC 7516: cifrado web JSON ( JWE ). 2015.
• IETF . RFC 7517: clave web JSON ( JWK ). 2015.
• IETF . RFC 7518 - Algoritmos web JSON ( JWA ). 2015.
• IETF . RFC 7519: token web JSON ( JWT ). 2015.
• IETF . RFC 7638: Huella digital de clave web JSON ( JWK ). 2015.
• IETF . RFC 7797: opción de carga útil sin codificar JWS . 2016.
• IETF . RFC 7800: Semántica clave de proof-of-possession para JWT . 2016.
• IETF . RFC 8037 - CFRG Curva Elíptica Diffie-Hellman y Firmas en JOSE . 2017.
• IETF . RFC 8725 / BCP 225: Mejores prácticas actuales de tokens web JSON . 2020.
• IETF . RFC 9068: perfil JWT para access tokens OAuth 2.0. 2021.
• IETF . RFC 9101: Solicitud de autorización protegida por OAuth 2.0 JWT . 2021.
• IETF . RFC 9278: URI de huella digital de JWK . 2022.
• IETF . RFC 9701: Respuesta de JWT para la introspección de tokens de OAuth . 2025.
• IETF . RFC 9864: Algoritmos completamente especificados para JOSE y COSE. 2025.
• IETF . RFC 9901: Divulgación selectiva para tokens web JSON . 2025.
• IANA . Registros JSON de firma y cifrado de objetos ( JOSE ).
• IANA . Registro de claims de tokens web JSON .
• Microsoft aprende. Políticas de validación- jwt y validación-azure-ad- token de Azure API Management.
• Documentación Axway. Filtros de validación, firma y cifrado API Gateway JWT .
• OWASP . Hoja de referencia de tokens web JSON para Java y hoja de referencia de seguridad OAuth 2.0.

Nota de actualización

Los algoritmos, registros y perfiles de JOSE continúan evolucionando. Antes de implementar una combinación, confirme el estado actual en el registro de la IANA , los RFC que actualizan la especificación y el soporte exacto de la biblioteca, HSM , proveedor de identidad y API Gateway .