Generar JWT

Utilice la política de seguridad Generar JWT en IBM® API Connect para generar una señal web JSON (JWT).

Soporte de pasarela

Tabla 1. Tabla que muestra qué puertas de enlace admiten esta política y la versión correspondiente de la misma
Pasarela	Versión de política
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.1.0

En este tema se describe cómo configurar la política en la interfaz de usuario de Assembly; para obtener más información sobre cómo configurar la política en la fuente de « OpenAPI », consulte jwt-generate.

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 Generar JWT le permite generar reclamaciones y configurar si se van a utilizar como carga útil de una estructura JWS (JSON Web Signature) o como texto sin formato de una estructura JWE (JSON Web Encryption). La especificación de material criptográfica para JWS y JWE genera una JWT anidada que está firmada digitalmente y cifrada. A continuación, el JWT se asigna a la cabecera de autorización como una señal portadora (la opción predeterminada), o a la variable de tiempo de ejecución en la propiedad JSON Web Token (JWT) , si se especifica.

Nota:

Para los tipos de algoritmo HS256, HS384 y HS512 los objetos criptográficos a los que se hace referencia deben ser una clave secreta compartida.
Para los tipos de algoritmo RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 los objetos criptográficos a los que se hace referencia deben ser una clave de cifrado (clave privada).
El material criptográfico se puede proporcionar a través de una Clave web JSON (JWK).
Si se especifican un objeto criptográfico y una JWK, el objeto criptográfico se utiliza para firmar la JWT.

Requisitos previos

Se aplican los requisitos previos siguientes:

Si utiliza uno o varios objetos criptográficos (objetos de cifrado), estos deben estar ubicados en el API Connect dominio del dispositivo DataPower. Los objetos criptográficos deben hacer referencia a la clave secreta compartida o al certificado necesario para cifrar o firmar el contenido de la JWT.
Si se utiliza una Clave web JSON (JWK), debe estar referenciada por una variable de tiempo de ejecución.

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. Generar propiedades de la política JWT
Etiqueta de propiedad	Obligatorio	Descripción	Tipo de datos
Título	Nee	El título de la política. El valor predeterminado es `jwt-generate`.	serie
Descripción	Nee	Una descripción de la política.	serie
Señal Web JSON (JWT)	Nee	Variable de tiempo de ejecución en la que se debe colocar la JWT que se genera. El valor predeterminado es `generated.jwt`. Sin embargo, si no se establece, la JWT que se genera se escribe en la cabecera de autorización como una señal portadora.	serie
Reclamación de ID de JWT	Nee	Indica si se debe añadir una reclamación de ID de JWT (jti) en la JWT. Si está seleccionada, la propiedad se establece en `true` y se genera un UUID que se establece como el valor de reclamación de JTI.	booleano
Reclamación del emisor	Sí	Variable de tiempo de ejecución desde la que se puede recuperar la serie de la reclamación Emisor (iss). Esta reclamación representa al Principal que ha emitido la JWT. El valor predeterminado es: `iss.claim`	serie
Reclamación de asunto	Nee	Variable de tiempo de ejecución desde la que se puede recuperar la serie de la reclamación Asunto (sub).	serie
Reclamación pública	Nee	Variable de tiempo de ejecución desde la que se puede recuperar la serie de la reclamación Pública (aud). Se han establecido varias variables mediante una serie separada por comas.	serie
Periodo de validez	Sí	El periodo de tiempo (en segundos), que se añade a la fecha y hora actuales, dentro del cual la JWT se considera válida. El valor predeterminado es `3600`.	entero
Reclamaciones privadas	Nee	Variable de tiempo de ejecución desde la que se puede recuperar un conjunto de reclamaciones JSON válidas. Estas reclamaciones se añaden a cualquier conjunto de reclamaciones especificado anteriormente.	serie
Nombre de variable JWK de firma	Nee	Variable de tiempo de ejecución que contiene la clave JWK utilizada para firmar el JWT. ^¹	serie
Algoritmo criptográfico	Nee	El algoritmo criptográfico que se utiliza. Los valores válidos son: HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 ES512 PS256 PS384 PS512	serie
Objeto criptográfico de firma	Nee	El objeto criptográfico que se utilizará para firmar el JWT. ^¹	serie
Signo del valor KID	Nee	El valor `kid` personalizado para la firma del JWT.	serie
Algoritmo de cifrado	Nee	El algoritmo de cifrado que se va a utilizar. Los valores válidos son: A128CBC-HS256 A192CBC-HS384 A256CBC-HS512	serie
Nombre de la variable JWK de cifrado	Nee	Variable de tiempo de ejecución que contiene el JWK que se va a utilizar para cifrar la JWT.	serie
Algoritmo de cifrado de clave	Nee	El algoritmo de cifrado de clave que se va a utilizar. Los valores válidos son: RSA1_5 RSA-OAEP RSA-OAEP-256 dir A128KW A192KW A256KW	serie
Objeto criptográfico de cifrado	Nee	El objeto criptográfico que se va a utilizar para cifrar la reclamación.	serie
Cifrar el valor KID	Nee	El valor `kid` personalizado para el cifrado JWT.	serie

Ejemplo

      - jwt-generate:
          version: 2.1.0
          title: jwt-generate
          description: New jwt-generate v2.1.0 policy.
          jwt: generated.jwt
          jti-claim: true
          iss-claim: iss.claim
          sub-claim: sub.claim
          aud-claim: aud.claim
          exp-claim: 3600
          private-claims: private.claims
          jws-jwk: jws.jwk
          jws-alg: HS256
          jws-crypto: jwsCryptoObjectName
          custom-kid-value-jws: jws.kid
          jwe-enc: A128CBC-HS256
          jwe-jwk: jwe.jwk
          jwe-alg: RSA1_5
          jwe-crypto: jweCryptoObjectName
          custom-kid-value-jwe: jwe.kid

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 el error, 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-generate.error-message, para que se pueda recuperar a través de captura.

Si no se configura una captura, en caso de fallo la política Generate JWT devuelve un error 500 Invalid-JWT-Generate de código HTTP. 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.

¹ Un JWK y un objeto criptográfico son formas válidas de proporcionar los datos criptográficos necesarios para firmar el JWT. Sin embargo, si se especifican ambos tipos de datos, sólo se utiliza el objeto criptográfico. Si utiliza uno o varios objetos criptográficos (objetos de cifrado), estos deben estar ubicados en el API Connect dominio del dispositivo DataPower. Los objetos criptográficos deben hacer referencia a la clave secreta compartida o al certificado necesario para cifrar o firmar el contenido de la JWT.