Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
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 |
|
| * 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 |
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 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: |
<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: |
<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 <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 |
| 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 <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 |
| Valor (elemento) | Obligatorio | Una clave secreta codificada. Especifica la clave secreta usada para firmar la carga útil.
Usa el atributo <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. |
|
|
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>