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
- 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 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 |
|
* 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 |
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 |
falso | Opcional |
habilitado | Configúralo como true para aplicar la política.Configúralo como |
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, |
<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: |
<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, |
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. |
|
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>