Política GenerateJWS

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

Qué

Genera un JWS firmado con un conjunto de reclamaciones configurables. El JWS se puede mostrar a los clientes, transmitido a los objetivos de backend o usarse de otras formas. Consulta la descripción general de las políticas de JWS y JWT para obtener una introducción detallada.

Para obtener información sobre las partes de un JWS y cómo se encriptan y firman, consulta RFC7515.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Video

Mira un video breve para aprender a generar un JWT firmado. Si bien este video es específico a fin de generar un JWT, muchos de los conceptos son los mismos para JWS.

Ejemplos

Verifica un JWS firmado con HS256

Esta política de ejemplo genera un JWS que se firma con el algoritmo HS256. HS256 se basa en un secreto compartido para firmar y verificar la firma. Este JWS usa contenido “adjunto”, lo que significa que el encabezado codificado, la carga útil y la firma se concatenan para producir el JWS final:

[header].[payload].[signature]

Usa el elemento <Payload> para especificar la carga útil JWS sin procesar y sin codificar. En este ejemplo, una variable contiene la carga útil. Cuando se activa esta acción de política, Apigee codifica el encabezado y la carga útil de JWS y, luego, agrega la firma codificada para firmar de forma digital el JWS.

La configuración de políticas que se muestra a continuación crea un JWS a partir de una carga útil contenida en la variable my-payload y almacena el JWS resultante en la variable output-variable.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="my-payload"/>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

Genera un JWT con firma HS256

En este ejemplo, también se genera un JWS con contenido adjunto que se firma con el algoritmo HS256. En este caso, la carga útil es JSON. Configurar el encabezado typ como JWT da como resultado un JWS firmado que también es un JWT firmado. (referencia)

La configuración de políticas que se muestra a continuación crea un JWS a partir de una carga útil contenida en la variable json-content y almacena el JWS resultante en la variable output-variable. El resultado será un JWT firmado si y solo si la variable json-content contiene una carga útil de JSON, y las propiedades dentro de esa carga útil de JSON son válidas para JWT. Por ejemplo, la propiedad exp, si está presente, debe contener un valor numérico. La propiedad aud, si está presente, debe ser una string o un array de strings. Y así sucesivamente. Consulta IETF RFC7519 para obtener detalles sobre los valores válidos de las reclamaciones JWT.

<GenerateJWS name="JWS-Generate-HS256-JWT">
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Payload ref="json-content"/>
    <AdditionalHeaders>
        <Claim name="typ">JWT</Claim>
    </AdditionalHeaders>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

Genera un JWS desconectado

Esta política de ejemplo genera un JWS con contenido desconectado, firmado con el algoritmo RS256. Generar de una firma RS256 se basa en una clave privada RSA, que se debe proporcionar en formato de codificación PEM.

Un JWS con contenido desconectado omite la carga útil del JWS generado:

[header]..[signature]

Usa el elemento <Payload> para especificar la carga útil JWS sin procesar y sin codificar. Cuando se activa esta política, Apigee codifica el encabezado y la carga útil de JWS y, luego, los usa para generar la firma codificada. Sin embargo, el JWS generado omite la carga útil codificada del JWS serializado. Esto es útil cuando el contenido firmado es grande o binario (como una imagen o PDF), o ambos. Para permitir la validación, debes pasar ambos elementos, el JWS y la carga útil que se incluyó en el contenido firmado a la parte que realiza la verificación. Si usas la política VerifyJWS para verificar el JWS, puedes especificar la variable que contiene la carga útil con el elemento <DetachedContent> de la política VerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="my-payload"/>
    <DetachContent>true</DetachContent>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

Configura los elementos clave

Los elementos que usas para especificar la clave utilizada para generar el JWS dependen del algoritmo elegido, como se muestra en la siguiente tabla:

Algoritmo Elementos clave
HS{256/384/512}*
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512}*
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Los elementos <Password> y <Id> son opcionales.

* Para obtener más información sobre los requisitos de las claves, consulta Información sobre los algoritmos de encriptación de firmas.

Referencia del elemento para Genera JWS

La referencia de política describe los elementos y atributos de la política de Genera JWS.

Nota: La configuración variará en función del algoritmo de encriptación que uses. Consulta Muestras para ver ejemplos que demuestran configuraciones específicas para casos de uso específicos.

Atributos que se aplican al elemento de nivel superior

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

Los siguientes atributos son comunes a todos los elementos superiores de la política.

Atributo Descripción Valor predeterminado Presencia
name El nombre interno de la política. Los caracteres que puede usar en el nombre están restringidos a: A-Z0-9._\-$ %. Sin embargo, la IU de Apigee aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos.

De forma opcional, usa el elemento <displayname></displayname> para etiquetar la política en el editor de proxy de IU de Apigee con un nombre de lenguaje natural diferente.

N/A Obligatorio
continueOnError Configúralo como false para devolver un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.

falso Opcional
habilitado Configúralo como true para aplicar la política.

Configúralo como false para “desactivar” la política. La política no se aplicará, incluso si permanece conectada a un flujo.

true Opcional
async Este atributo dejó de estar disponible. falso Obsoleta

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Además de usar el atributo de nombre para etiquetar la política en el editor de proxy de IU de Apigee con un nombre diferente y con lenguaje natural.

Configuración predeterminada Si omites este elemento, se usa el valor del atributo de nombre de la política.
Presencia Opcional
Tipo String

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica el algoritmo de encriptación para firmar el token.

Valor predeterminado N/A
Presencia Obligatorio
Tipo String
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Coloca los pares nombre-valor de reclamo adicionales en el encabezado de la JWS.

Valor predeterminado N/A
Presencia Opcional
Valores válidos Cualquier valor que desees usar para una reclamación adicional. Puedes especificar las reclamaciones de forma explícita como una string, un número, un valor booleano, un mapa o un arreglo.

El elemento <Claim> incluye los siguientes atributos:

  • name: Es el nombre de la reclamación, también conocido como parámetro (obligatorio).
  • ref: El nombre de una variable de flujo (opcional). Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican un atributo ref y un valor de reclamación explícito, el valor explícito es el predeterminado y se usa si la variable de flujo a la que se hace referencia no se resuelve.
  • type: (Opcional) uno de los siguientes: string, (predeterminado), número, booleano o mapa.
  • arreglo: (Opcional) Establece en true para indicar si el valor es un arreglo de tipos. Valor predeterminado: false

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref="variable_containing_headers"/>

Agrega el encabezado crítico, crit, a la JWS. El encabezado crit es un arreglo de nombres de encabezados que el receptor JWS debe conocer y reconocer. Por ejemplo, puedes usar este elemento de configuración para producir un encabezado JWS que, cuando se decodifique, se vea así:

{
  "typ": "...",
  "alg" : "...",
  "hyb" : "some-value-here",
  "crit" : [ "hyb" ],
}

Este encabezado JWS confirma que el parámetro de encabezado hyb es de importancia crítica, y cualquier destinatario del JWS debe comprender el significado y el valor de ese parámetro.

Según IETF RFC 7515, el destinatario de un JWS debe rechazar el JWS como no válido si el destinatario no comprende uno o más de los parámetros a los que se hace referencia en el crit. En Apigee, la política VerifyJWS cumple con este comportamiento. Para cada parámetro enumerado en el parámetro crit, comprueba que el elemento <KnownHeaders> de la política VerifyJWS también enumere ese parámetro. Cualquier encabezado que encuentre la política VerifyJWS en crit que no aparezca en <KnownHeaders> hará que la política VerifyJWS rechace el JWS.

Valor predeterminado N/A
Presencia Opcional
Tipo Array separado por comas de una o más strings
Valores válidos Un array o una referencia a una variable que contiene el array.

<DetachContent>

<DetachContent>true|false</DetachContent>

Especifica si se debe generar el JWS con una carga útil separada, <DetachContent>true</DetachContent> o no, <DetachContent>false</DetachContent>.

Si especificas falso, el JWS generado de forma predeterminada tendrá el siguiente formato:

[header].[payload].[signature]

Si especificas verdadero para crear un JWS con una carga útil desconectada, el JWS generado omite la carga útil y tiene el siguiente formato:

[header]..[signature]

Con un JWS que usa una carga útil desconectada, depende de ti pasar la carga útil original sin codificar a la parte que realiza la verificación, junto con el JWS serializado.

Valor predeterminado falso
Presencia Opcional
Tipo Booleano
Valores válidos True o False

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Configúralo como false si deseas que la política muestre un error cuando no se pueda resolver cualquier variable a la que se especifica en la política. Se establece como true para tratar cualquier variable no recuperable como una string vacía (null).

Valor predeterminado falso
Presencia Opcional
Tipo Booleano
Valores válidos True o False

<OutputVariable>

<OutputVariable>output-variable</OutputVariable>

Especifica el nombre de la variable de contexto que la política establecerá con el JWS generado. De forma predeterminada, la política coloca el JWS en la variable de contexto llamada jws.POLICYNAME.generated_jws.

Valor predeterminado jws.POLICYNAME.generated_jws
Presencia Opcional
Tipo String (un nombre de variable de flujo)

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Especifica la carga útil de JWS sin procesar y sin codificar. Especifica una variable que contenga la carga útil o una string.

Valor predeterminado N/A
Presencia Obligatorio
Tipo String, arreglo de bytes, transmisión o cualquier otra representación de la carga útil de JWS sin codificación.
Valores válidos Una plantilla de mensaje o una referencia a una variable que contiene la carga útil.

Elemento <PrivateKey>

Es opcional, solo para usar cuando <Algorithm> es una de las opciones RS*, PS* o ES*. Especifica la clave privada que se usará para la firma, así como otra información relacionada con la clave privada. Se usa cuando el algoritmo es asimétrico.

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>
Predeterminado: N/A
Presencia: Opcional. Sin embargo, debes incluir exactamente uno de los elementos <PrivateKey> o <SecretKey>. Usa el elemento <PrivateKey> cuando el algoritmo es RS*, PS* o ES*, y usa el elemento <SecretKey> cuando el algoritmo es HS*.
Tipo: N/A

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Especifica el ID de clave (kid) que se incluirá en el encabezado JWS.

Valor predeterminado N/A
Presencia Opcional
Tipo String
Valores válidos String o variable de flujo

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Especifica la contraseña que debe usar la política para desencriptar la clave privada, si es necesario. Usa el atributo ref para pasar la clave en una variable de flujo.

Valor predeterminado N/A
Presencia Opcional
Tipo String
Valores válidos

Una referencia de variable de flujo. Nota: Debes especificar una variable de flujo con el atributo ref. Apigee rechazará la configuración de la política como no válida en la que la contraseña se especifica en texto simple. La variable de flujo debe tener el prefijo “privado”. Por ejemplo: private.mypassword

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Especifica una clave privada con codificación PEM que se usa para firmar el JWS. Usa el atributo ref para pasar la clave en una variable de flujo.

Valor predeterminado N/A
Presencia Obligatorio cuando se usa la política para generar un JWS con uno de los algoritmos RS*, PS* o ES*.
Tipo String
Valores válidos Una variable de flujo que contiene una string que representa un valor de clave privada con codificación PEM.

Nota: La variable de flujo debe tener el prefijo “privado”. Por ejemplo:private.mykey

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

Especifica la clave secreta que se usará cuando se genere un JWS que use un algoritmo simétrico (HS*), que puede ser HS256, HS384 o HS512.

Este elemento es opcional. Sin embargo, debes incluir exactamente uno de los elementos <PrivateKey> o <SecretKey>. Usa el elemento <PrivateKey> cuando generes un JWS firmado con un algoritmo asimétrico (puede ser RS*, PS* o ES*) y usa el elemento <SecretKey> cuando generes un JWS con el un algoritmo simétrico (algoritmo como HS*).

Secundarios de <SecretKey>

En la siguiente tabla, se proporciona una descripción de los elementos secundarios y los atributos de <SecretKey>:

Secundario Presencia Descripción
codificación (atributo) Opcional

Especifica cómo se codifica la clave en la variable a la que se hace referencia. De forma predeterminada, cuando no hay un atributo encoding presente, la codificación de la clave se trata como UTF-8. Estos son los valores válidos para el atributo: hex, base16, base64 o base64url. Los valores de codificación hex y base16 son sinónimos.

<SecretKey encoding="hex" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.secretkey"/>
</SecretKey>

En el ejemplo anterior, debido a que la codificación es hex, si el contenido de la variable private.secretkey es 494c6f766541504973, la clave se decodificará como un conjunto de 9 bytes, que en hex será 49 4c 6f 76 65 41 50 49 73.

ID (elemento) Opcional

El identificador de clave. El valor puede ser cualquier cadena. Puedes especificar el valor como un valor de texto literal o de forma indirecta a través de una referencia de variable con el atributo ref.

<SecretKey>
  <Id ref="flow-variable-name-here"/>
  <Value ref="private.variable-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

La política incluirá este identificador de clave como la reclamación kid en el encabezado del JWS generado.

Valor (elemento) Obligatorio

Una clave secreta codificada. Especifica la clave secreta usada para firmar la carga útil. Usa el atributo ref para proporcionar la clave de forma indirecta a través de una variable, como private.secret-key.

<SecretKey>
  <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee aplica una seguridad de clave mínima para los algoritmos HS256/HS384/HS512. La longitud mínima de la clave de HS256 es de 32 bytes, para HS384 es de 48 bytes, y para HS512 es de 64 bytes. El uso de una clave de baja intensidad provoca un error en el entorno de ejecución.

<Type>

<Type>type-string-here</Type>

Elemento opcional cuyo único valor permitido es Signed y especifica que la política genera un JWS firmado. <Type> se proporciona solo para hacer coincidir el elemento correspondiente para las políticas GenerateJWT y VerifyJWT (en las que puede tomar cualquiera de los valores Signed o Encrypted).

Valor predeterminado N/A
Presencia Opcional
Tipo String
Valor válido Signed

Variables de flujo

La política Generar JWS no establece variables de flujo.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Lo que necesitas saber sobre errores de políticas y Controla fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Ocurre cuando
steps.jws.GenerationFailed 401 La política no pudo generar el JWS.
steps.jws.InsufficientKeyLength 401 En el caso de una clave de menos de 32 bytes para el algoritmo HS256
steps.jws.InvalidClaim 401 Para una reclamación faltante o una falta de coincidencia de una reclamación, o bien un encabezado faltante o una falta de coincidencia de un encabezado.
steps.jws.InvalidCurve 401 La curva especificada por la clave no es válida para el algoritmo de curva elíptica.
steps.jws.InvalidJsonFormat 401 Se encontró un archivo JSON que no es válido en el encabezado JWS.
steps.jws.InvalidPayload 401 La carga útil JWS no es válida.
steps.jws.InvalidSignature 401 <DetachedContent> se omite y la JWS tiene una carga útil de contenido desconectada.
steps.jws.KeyIdMissing 401 La política de verificación usa un JWKS como fuente para las claves públicas, pero el JWS firmado no incluye una propiedad kid en el encabezado.
steps.jws.KeyParsingFailed 401 No se pudo analizar la clave pública a partir de la información de claves determinada.
steps.jws.MissingPayload 401 Falta la carga útil JWS.
steps.jws.NoAlgorithmFoundInHeader 401 Ocurre cuando el JWS omite el encabezado del algoritmo.
steps.jws.SigningFailed 401 En GenerateJWS, ocurre en el caso de una clave que es menor que el tamaño mínimo para los algoritmos HS384 o HS512.
steps.jws.UnknownException 401 Se produjo una excepción desconocida.
steps.jws.WrongKeyType 401 El tipo de clave especificado es incorrecto. Por ejemplo, si especificas una clave RSA para un algoritmo de curva elíptica o una clave de curva para un algoritmo de RSA.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Ocurre cuando
InvalidAlgorithm Los únicos valores válidos son RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Otros errores de implementación posibles.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "TokenExpired"
JWS.failed Todas las políticas de JWS establecen la misma variable en caso de falla. jws.JWS-Policy.failed = true

Ejemplo de respuesta de error

Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

Ejemplo de regla de falla

<FaultRules>
    <FaultRule name="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>