Política GenerateJWS

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X.
información

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.

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.

Muestras

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

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 JWS, y 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:

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 administración de Edge aplica reglas restricciones, 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 la IU de administración 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 administración con un nombre diferente y con lenguaje natural.

Valor predeterminado 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: 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.

Predeterminada N/A
Presencia Opcional
Tipo Arreglo de strings separadas por comas
Valores válidos Un arreglo o el nombre de una variable que contiene el arreglo.

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

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

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

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

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

Predeterminada N/A
Presencia Opcional
Tipo String
Valores válidos Una referencia de variable de flujo.

Nota: Debes especificar una variable de flujo. Edge rechazará un elemento como no válido de política 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. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predeterminada N/A
Presencia Se necesita para generar un JWS mediante el algoritmo RS256.
Tipo String
Valores válidos Una variable de flujo que contiene una string que representa un valor de clave privada RSA con codificación PEM.

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

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

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

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

Predeterminada N/A
Presencia Obligatorio para los algoritmos HMAC.
Tipo String
Valores válidos Una variable de flujo que hace referencia a una string.

Nota: Si una variable de flujo, debe tener el prefijo "private". Por ejemplo, private.mysecret

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 fallas que establece 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.

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 Porque falta un reclamo o un reclamo, o bien el encabezado o el encabezado no coinciden.
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 JSON no válido en el encabezado JWS.
steps.jws.InvalidPayload 401 La carga útil de 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 Verificar 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 clave proporcionada.
steps.jws.MissingPayload 401 Falta la carga útil de 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 posibles errores de implementación

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>