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 configurable. El JWS se puede devolver a los clientes, transmitir a los destinos de backend o usar de otras formas. Consulta la información general sobre 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 cifran y firman, consulta el estándar RFC7515.
Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.
Vídeo
Echa un vistazo a este breve vídeo para aprender a generar un JWT firmado. Aunque este vídeo se centra en la generación de un JWT, muchos de los conceptos son los mismos para JWS.
Ejemplos
Generar un JWS firmado con HS256
Esta política de ejemplo genera un JWS firmado 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, la carga útil y la firma codificados se concatenan con puntos para generar el JWS final:
[header].[payload].[signature]
Use el elemento <Payload> para especificar la carga útil de JWS 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, a continuación, añade la firma codificada para firmar digitalmente el JWS.
La configuración de la política 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>
Generar un JWT firmado con 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. Si se define el encabezado typ como JWT,
se obtiene un JWS firmado que también es un JWT firmado.
(referencia)
La configuración de la política 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 JSON y las propiedades de esa carga útil JSON son válidas para JWT. Por ejemplo, la propiedad exp, si está presente, debe tener un valor numérico. La propiedad aud, si está presente,
debe ser una cadena o una matriz de cadenas. Y así sucesivamente. Consulta el RFC7519 de IETF para obtener más información sobre los valores válidos de las reclamaciones de 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>
Generar un JWS independiente
Esta política de ejemplo genera un JWS con contenido independiente, firmado con el algoritmo RS256. Para generar una firma RS256, se necesita una clave privada RSA, que debe proporcionarse en formato codificado con PEM.
Un JWS con contenido independiente omite la carga útil del JWS generado:
[header]..[signature]
Use el elemento <Payload> para especificar la carga útil de JWS sin codificar.
Cuando se activa esta política, Apigee codifica el encabezado y la carga útil de JWS y, a continuación, los usa para generar la firma codificada. Sin embargo, el JWS generado omite la carga útil codificada del JWS serializado. Esto resulta útil cuando el contenido firmado es grande o binario (como una imagen o un PDF) o ambas cosas. Para permitir la validación, debes enviar ambos elementos (el JWS y la carga útil incluida en el contenido firmado) a la parte verificadora. 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>
Definir los elementos clave
Los elementos que se usan 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 Acerca de los algoritmos de cifrado de firmas. | ||
Referencia de elementos de Generate JWS
En la referencia de la política se describen los elementos y atributos de la política Generate JWS.
Nota: La configuración variará ligeramente en función del algoritmo de cifrado que utilices. Consulta los ejemplos para ver configuraciones de casos prácticos 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 principales de la política.
| Atributo | Descripción | Predeterminado | Presencia |
|---|---|---|---|
| name |
El nombre interno de la política. Solo puedes usar los siguientes caracteres en el nombre:
A-Z0-9._\-$ %. Sin embargo, la interfaz de usuario de Apigee aplica restricciones adicionales, como la eliminación automática de caracteres que no son alfanuméricos.
También puedes usar el elemento |
N/A | Obligatorio |
| continueOnError |
Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.
Asigna el valor |
falso | Opcional |
| habilitada |
Asigna el valor true para aplicar la política.
Selecciona |
true | Opcional |
| asíncrono | Este atributo está obsoleto. | falso | Obsoleto |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Se usa junto con el atributo name para etiquetar la política en el editor de proxies de la interfaz de usuario de Apigee con un nombre diferente en lenguaje natural.
| Predeterminado | Si omite este elemento, se usará el valor del atributo name de la política. |
| Presencia | Opcional |
| Tipo | Cadena |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
Especifica el algoritmo de cifrado para firmar el token.
| Predeterminado | N/A |
| Presencia | Obligatorio |
| Tipo | Cadena |
| Valores válidos | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 y 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 la reclamación adicional en el encabezado del JWS.
| Predeterminado | N/A |
| Presencia | Opcional |
| Valores válidos | Cualquier valor que quieras usar para una reclamación adicional. Puedes especificar la reclamación explícitamente como cadena, número, valor booleano, mapa o matriz. |
El elemento <Claim> acepta estos atributos:
- name: obligatorio. Es el nombre de la reclamación, también conocido como parámetro.
- ref: (opcional) Nombre de una variable de flujo. Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican tanto un atributo ref como un valor de reclamación explícito, el valor explícito será el predeterminado y se usará si la variable de flujo a la que se hace referencia no se resuelve.
- type: (opcional) uno de los siguientes valores: string (valor predeterminado), number, boolean o map.
- array: (opcional) asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false.
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref="variable_containing_headers"/>
Añade el encabezado crítico, crit, al JWS. La cabecera crit es una matriz de nombres de cabeceras que debe conocer y reconocer el receptor de JWS. Por ejemplo, puede usar este elemento de configuración para generar un encabezado JWS que, al decodificarse, tenga este aspecto:
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}Este encabezado JWS afirma que el parámetro de encabezado hyb es de importancia crítica y que cualquier destinatario del JWS debe entender el significado y el valor de ese parámetro.
Según el RFC 7515 de IETF, el destinatario de un JWS debe rechazarlo como no válido si no entiende uno o varios de los parámetros a los que se hace referencia en el parámetro crit. En Apigee, la política VerifyJWS se ajusta a este comportamiento.
Por cada parámetro que aparece en el parámetro crit, se comprueba que el elemento <KnownHeaders> de la política VerifyJWS también incluya ese parámetro.
Si la política VerifyJWS encuentra en crit una cabecera que no aparece en <KnownHeaders>, la política VerifyJWS rechazará el JWS.
| Predeterminado | N/A |
| Presencia | Opcional |
| Tipo | Array de una o varias cadenas separadas por comas. |
| Valores válidos | Una matriz o una referencia a una variable que contenga la matriz. |
<DetachContent>
<DetachContent>true|false</DetachContent>
Especifica si se debe generar el JWS con una carga útil independiente (<DetachContent>true</DetachContent>) o no (<DetachContent>false</DetachContent>).
Si especificas el valor predeterminado (false), el JWS generado tendrá el siguiente formato:
[header].[payload].[signature]
Si especificas "true" para crear un JWS con una carga útil independiente, el JWS generado omitirá la carga útil y tendrá el siguiente formato:
[header]..[signature]
En el caso de un JWS con una carga útil independiente, debes enviar la carga útil original sin codificar a la parte verificadora junto con el JWS serializado.
| Predeterminado | falso |
| Presencia | Opcional |
| Tipo | Booleano |
| Valores válidos | verdadero o falso |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Asigna el valor false si quieres que la política genere un error cuando no se pueda resolver ninguna variable de referencia especificada en la política. Se define como true para tratar cualquier variable que no se pueda resolver como una cadena vacía (nula).
| Predeterminado | falso |
| Presencia | Opcional |
| Tipo | Booleano |
| Valores válidos | verdadero o falso |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
Especifica el nombre de la variable de contexto que la política definirá con el JWS generado.
De forma predeterminada, la política coloca el JWS en la variable de contexto llamada
jws.POLICYNAME.generated_jws.
| Predeterminado | jws.POLICYNAME.generated_jws |
| Presencia | Opcional |
| Tipo | Cadena (nombre de una variable de flujo) |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
Especifica la carga útil de JWS sin codificar. Especifica una variable que contenga la carga útil o una cadena.
| Predeterminado | N/A |
| Presencia | Obligatorio |
| Tipo | Cadena, matriz de bytes, flujo o cualquier otra representación de la carga útil de JWS sin codificar. |
| Valores válidos | Una plantilla de mensaje o una referencia a una variable que contenga la carga útil. |
Elemento <PrivateKey>
Es opcional y solo se usa cuando <Algorithm> es una de las opciones RS*, PS* o ES*. Especifica la clave privada que se va a usar para firmar, 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>
| Valor predeterminado: | N/A |
| Presencia: | Opcional. Sin embargo, debe incluir exactamente uno de los elementos <PrivateKey> o <SecretKey>.
Usa el elemento <PrivateKey> cuando el algoritmo sea RS*, PS* o ES*,
y el elemento <SecretKey> cuando el algoritmo sea 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 debe incluir en el encabezado JWS.
| Predeterminado | N/A |
| Presencia | Opcional |
| Tipo | Cadena |
| Valores válidos | Una variable de flujo o una cadena |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
Especifica la contraseña que debe usar la política para descifrar la clave privada, si es necesario. Usa el atributo ref para transferir la clave en una variable de flujo.
| Predeterminado | N/A |
| Presencia | Opcional |
| Tipo | Cadena |
| Valores válidos |
Referencia a una variable de flujo. Nota: Debe especificar una variable de flujo con el atributo ref. Apigee rechazará como no válida una configuración de política en la que la contraseña se especifique en texto sin cifrar. La variable de flujo
debe tener el prefijo "private". Por ejemplo, |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
Especifica una clave privada codificada en PEM que se usa para firmar el JWS. Usa el atributo ref para transferir la clave en una variable de flujo.
| 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 | Cadena |
| Valores válidos |
Una variable de flujo que contiene una cadena que representa un valor de clave privada codificado en PEM.
Nota: La variable de flujo debe tener el prefijo "private". 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á al generar un JWS que utilice un algoritmo simétrico (HS*), como HS256, HS384 o HS512.
Este elemento es opcional. Sin embargo, debe incluir exactamente uno de los elementos <PrivateKey> o <SecretKey>.
Usa el elemento <PrivateKey> cuando generes un JWS firmado con un algoritmo asimétrico (uno de RS*, PS* o ES*) y el elemento <SecretKey> cuando generes un JWS firmado con un algoritmo simétrico (como HS*).
Hijos de <SecretKey>
En la siguiente tabla se describen los elementos secundarios y los atributos de <SecretKey>:
| Hijo/a | 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, si no se incluye el atributo <SecretKey encoding="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> En el ejemplo anterior, como la codificación es |
| Id (elemento) | Opcional | Identificador de la clave. El valor puede ser cualquier cadena. Puede especificar el valor como un valor de texto literal o, de forma indirecta, mediante 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 que se usa para firmar la carga útil.
Utilice el atributo <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee aplica una longitud mínima de clave para los algoritmos HS256, HS384 y HS512. La longitud mínima de la clave de HS256 es de 32 bytes, la de HS384 es de 48 bytes y la de HS512 es de 64 bytes. Si se usa una clave con una seguridad inferior, se produce un error de tiempo de ejecución. |
<Type>
<Type>type-string-here</Type>
Elemento opcional cuyo único valor permitido es Signed, que especifica que la política genera un JWS firmado. <Type> se proporciona
solo para que coincida con el elemento correspondiente de las políticas GenerateJWT y VerifyJWT (donde
puede adoptar cualquiera de los valores Signed o Encrypted).
| Predeterminado | N/A |
| Presencia | Opcional |
| Tipo | Cadena |
| Valor válido | Signed |
Variables de flujo
La política Generar JWS no define variables de flujo.
Referencia de errores
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
| Fault code | HTTP status | Occurs when |
|---|---|---|
steps.jws.GenerationFailed |
401 |
The policy was unable to generate the JWS. |
steps.jws.InsufficientKeyLength |
401 |
For a key less than 32 bytes for the HS256 algorithm |
steps.jws.InvalidClaim |
401 |
For a missing claim or claim mismatch, or a missing header or header mismatch. |
steps.jws.InvalidCurve |
401 |
The curve specified by the key is not valid for the Elliptic Curve algorithm. |
steps.jws.InvalidJsonFormat |
401 |
Invalid JSON found in the JWS header. |
steps.jws.InvalidPayload |
401 |
The JWS payload is invalid. |
steps.jws.InvalidSignature |
401 |
<DetachedContent> is omitted and the JWS has a detached content payload. |
steps.jws.KeyIdMissing |
401 |
The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not
include a kid property in the header. |
steps.jws.KeyParsingFailed |
401 |
The public key could not be parsed from the given key information. |
steps.jws.MissingPayload |
401 |
The JWS payload is missing. |
steps.jws.NoAlgorithmFoundInHeader |
401 |
Occurs when the JWS omits the algorithm header. |
steps.jws.SigningFailed |
401 |
In GenerateJWS, for a key less than the minimum size for the HS384 or HS512 algorithms |
steps.jws.UnknownException |
401 |
An unknown exception occurred. |
steps.jws.WrongKeyType |
401 |
Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm. |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
| Error name | Occurs when |
|---|---|
InvalidAlgorithm |
The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512. |
|
|
Other possible deployment errors. |
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
| Variables | Where | Example |
|---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "TokenExpired" |
JWS.failed |
All JWS policies set the same variable in the case of a failure. | jws.JWS-Policy.failed = true |
Example error response
For error handling, the best practice is to trap the errorcode part of the error
response. Do not rely on the text in the faultstring, because it could change.
Example fault rule
<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>