Política GenerateJWS

Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X.

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.

Para videos

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.

Muestras

• Verifica un JWS conectado firmado con el algoritmo HS256
• Genera un JWS separado firmado con el algoritmo RS256

Verifica un JWS conectado firmado con el algoritmo HS256

Esta política de ejemplo genera un JWS conectado y lo firma con el algoritmo HS256. HS256 se basa en un secreto compartido para firmar y verificar la firma.

Un JWS adjunto contiene el encabezado codificado, la carga útil y la firma:

header.payload.signature

Configura <DetachContent> como verdadero para generar contenido desconectado. Consulta Partes de un JWS/JWT para obtener más información sobre la estructura y el formato de un JWS.

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, Edge codifica el encabezado y la carga útil de JWS y, luego, agrega la firma codificada para firmar JWS de forma digital.

La siguiente configuración de política crea un JWS a partir de una carga útil contenida en la variable private.payload.

<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="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Genera un JWS desconectado firmado con el algoritmo RS256

Esta política de ejemplo genera un JWS desconectado y lo firma 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 desconectado omite la carga útil del JWS:

header..signature

Usa el elemento <Payload> para especificar la carga útil JWS sin procesar y sin codificar. Cuando se activa esta política, Edge 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. Depende de ti pasar la carga útil a la política VerifyJWS mediante 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="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-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:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

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

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.

<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 administración con un nombre diferente y con lenguaje natural.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<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.

El elemento <Claim> incluye los siguientes atributos:

• name: El nombre del reclamo (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:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

En el entorno de ejecución, la política VerifyJWS examina el encabezado crit. Para cada encabezado enumerado en el encabezado crit, verifica que el elemento <KnownHeaders> de la política VerifyJWS también enumere ese encabezado. Cualquier encabezado que la política VerifyJWS encuentre en crit que no esté incluido en <KnownHeaders> provoca que la política VerifyJWS falle.

<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 true para crear una carga útil separada, el JWS generado omite la carga útil y tiene el siguiente formato:

header..signature

Con una carga útil desconectada, depende de ti pasar la carga útil original sin codificación a la política VerifyJWS mediante el elemento <DetachedContent> de la política VerifyJWS.

<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).

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Especifica dónde se debe colocar el JWS que genera esta política. De forma predeterminada, se ubica en la variable de flujo jws.POLICYNAME.generated_jws.

<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.

<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. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<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. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<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. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<SecretKey/Id>

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

or

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

Especifica el ID de clave (kid) que se incluirá en el encabezado JWS de un JWS firmado con un algoritmo HMAC. Úsalo solo cuando el algoritmo sea uno de HS256/HS384/HS512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Proporciona la clave secreta usada para verificar o firmar tokens con un algoritmo HMAC. Úsalo solo cuando el algoritmo sea uno de HS256/HS384/HS512. Usa el atributo ref para pasar la clave en una variable de flujo.

Edge aplica una intensidad 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.

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 y mensajes de error que se muestran, y las variables de error que configura Edge 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.

Errores en la implementación

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

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.

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>