Validar JWT

Utilice la política de seguridad Validar JWT para habilitar la validación de una señal web JSON (JWT) en una solicitud antes de permitir el acceso a las API.

Soporte de pasarela

Tabla 1. Tabla que muestra qué pasarelas soportan esta política y la versión de política correspondiente
Pasarela	Versión de política
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

En este tema se describe cómo configurar la política en la interfaz de usuario de ensamblaje. Para obtener detalles sobre cómo configurar la política en el origen de OpenAPI , consulte jwt-validate.

Acerca de

La Señal web JSON (JWT) es una manera compacta, con seguridad de URL de representar reclamaciones que se van de transferir entre dos partes. La política Validar JWT le permite proteger el acceso a las API utilizando la validación de JWT. Por ejemplo, cuando se recibe una solicitud de entrada que contiene un JWT en la cabecera, la política Validar JWT extrae la señal, verifica y descifra (si procede) la firma y valida la reclamación. Si es válida, la reclamación se pone en una variable de tiempo de ejecución (para utilizarla después si es necesario) y se permite el acceso a la API. Si la reclamación no es válida, se deniega el acceso.

Todas las reclamaciones especificadas en la política Validar JWT se validan, pero esto no es necesariamente todas las reclamaciones contenidas en la JWT. No todas las reclamaciones que están en el JWT deben validarse, pero si alguna de las reclamaciones especificadas en la política Validar JWT falla, la validación completa falla. Si la validación es satisfactoria, el conjunto completo de reclamaciones contenidas en el JWT se graban en la variable de tiempo de ejecución especificada en la propiedad Output Claims . Con ello se permite que cualquier acción posterior utilice esta variable de tiempo de ejecución para seguir validando el conjunto completo de reclamaciones que estaban en la JWT, según sea necesario.

Nota:

Si el mensaje original estaba firmado con una clave secreta compartida, el objeto criptográfico especificado debe ser también una clave secreta compartida.
Si el mensaje original era una clave privada, el objeto criptográfico especificado debe ser un certificado criptográfico (certificado público).
El material criptográfico se puede proporcionar a través de una Clave web JSON (JWK).
Si se incluye un parámetro de cabecera JWK en la cabecera de la JWT, el parámetro debe coincidir con la JWK o el objeto criptográfico especificado en la política o de lo contrario, la validación de la JWT fallará.
Si se especifican un objeto criptográfico y una JWK, el objeto criptográfico se utiliza para descifrar o verificar la JWT.
La acción de validación JWT en DataPower API Gateway puede verificar un JWT utilizando un único JWK o un conjunto JWK.

Requisitos previos

Se aplican los siguientes requisitos previos:

IBM® DataPower V7.5 con la opción de optimización de aplicaciones (AO).
Si está utilizando uno o más objetos criptográficos (objetos criptográficos), deben estar ubicados en el dominio IBM API Connect en el DataPower dispositivo. Los objetos criptográficos deben hacer referencia a la clave secreta compartida o al certificado público necesario para descifrar el contenido de la JWT o verificar la firma.
Si se está utilizando una clave web JSON (JWK) o un conjunto JWK, una variable de tiempo de ejecución debe hacer referencia a la misma.

Propiedades

En la tabla siguiente se listan las propiedades de política, se indica si se requiere una propiedad, y se especifica los valores válidos y predeterminados para la entrada, así como el tipo de datos de los valores.

Tabla 2. Propiedades de política de Validar JWT
Etiqueta de propiedad	Obligatorio	Descripción	Tipo de datos
Título	Sí	El título de la política. El valor predeterminado es `jwt-validate`.	serie
Descripción	Nee	Una descripción de la política.	serie
Señal Web JSON (JWT)	Sí	Variable de contexto o de tiempo de ejecución que contiene la JWT que se va a validar. El valor predeterminado es `request.headers.authorization`. Sin embargo, si esta propiedad no está establecida, la política busca de forma predeterminada la JWT en la ubicación `request.headers.authorization`. Nota: El formato de la cabecera de autorización debe ser: `"Authorization: Bearer jwt-token"` donde `señal_JWT` es la JWT codificada.	serie
Reclamaciones de salida	Sí	Variable de tiempo de ejecución a la que se asigna el conjunto completo de reclamaciones que están contenidas en la JWT. El valor predeterminado es `decoded.claims`.	serie
Reclamación del emisor	Nee	Las Perl Compatible Regular Expressions (PCRE) que se utilizan para validar la reclamación Emisor (iss).	serie
Reclamación pública	Nee	La PCRE que se va a utilizar para validar la reclamación Público (aud).	serie
Objeto de criptográfico de descifrado	Nee	El objeto criptográfico (una clave o certificado compartido) que se debe utilizar para decodificar la reclamación.^¹	serie
Nombre de la variable JWK criptográfica de descifrado	Nee	Variable de tiempo de ejecución que contiene el JWK a utilizar para descifrar el JWT.^¹	serie
Objeto criptográfico de verificación	Nee	El objeto criptográfico (una clave o certificado compartido) que se debe utilizar para verificar la firma.^²	serie
Nombre de la variable JWK criptográfica de verificación	Nee	Variable de tiempo de ejecución que contiene el JWK, o conjunto JWK, que se debe utilizar para verificar la firma.^²	serie

Ejemplo

- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

Errores

Se puede generar el siguiente error mientras se ejecuta la política:

RuntimeError: se trata de un error genérico que captura todos los errores que se producen durante la ejecución de la política. Cuando se produce un error de validación, el mensaje de error detallado que se recibe del módulo JOSE subyacente se escribe en el registro del sistema predeterminado como mensaje de error. Este mensaje de error detallado se asigna también a la variable de tiempo de ejecución jwt-validate.error-message, para que se pueda recuperar a través de captura.

HTTP Si no se configura una captura, en caso de fallo de validación la política Validate JWT devuelve un fallo de código 500 Invalid-JWT-Validate. El mensaje de error detallado del módulo JOSE subyacente se puede encontrar en el registro del sistema.

Atención: Si es un desarrollador de API que está resolviendo un error que uno de sus clientes ha tenido con la API, tenga en cuenta los riesgos de seguridad antes de enviar a un cliente el contenido exacto del mensaje de registro. Puede evitar la posibilidad de que alguien lance un ataque basándose en la información recibida en el mensaje de registro enviando al cliente solo información general sobre el mensaje.

Para ver ejemplos, consulte jwt-validate.

¹ Un JWK y un objeto criptográfico son formas válidas de proporcionar los datos criptográficos necesarios para descifrar el JWT. Sin embargo, si se especifican ambos tipos de datos, sólo se utiliza el objeto criptográfico. Si está utilizando uno o más objetos criptográficos (objetos criptográficos), deben estar ubicados en el dominio IBM API Connect en el DataPower dispositivo. Los objetos criptográficos deben hacer referencia a la clave secreta compartida o al certificado público necesario para descifrar el contenido de la JWT o verificar la firma.

² Un conjunto JWK, o JWK, y un objeto criptográfico son formas válidas de proporcionar los datos criptográficos necesarios para verificar el JWT. Sin embargo, si se especifican ambos tipos de datos, sólo se utiliza el objeto criptográfico.