Política DecodeJWS

Esta página se aplica a Apigee y Apigee hybrid.

Consulta la documentación de Apigee Edge.

La política DecodeJWS decodifica el encabezado JWS sin verificar la firma del JWS y escribe cada encabezado en una variable de flujo. Esta política es más útil cuando se usa junto con la política VerifyJWS, cuando se debe conocer el valor de un encabezado de JWS antes de verificar la firma de JWS.

Un JWS puede tener una carga útil adjunta, como en el siguiente formato:

header.payload.signature

También puede omitir la carga útil, denominada carga útil independiente, y tener el siguiente formato:

header..signature

La política DecodeJWS funciona con ambos formularios porque solo decodifica la parte del encabezado del JWS. La política DecodeJWS también funciona independientemente del algoritmo que se haya usado para firmar el JWS.

Consulta la información general sobre las políticas de JWS y JWT para ver una introducción detallada y un resumen del formato de un JWS.

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.

Ejemplo: decodificar un JWS

La política que se muestra a continuación decodifica un JWS que se encuentra en la variable de flujo var.JWS. Esta variable debe estar presente y contener un JWS viable (decodificable). La política puede obtener el JWS de cualquier variable de flujo.

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

Para cada encabezado de la sección de encabezados del JWS, la política define una variable de flujo denominada:

jws.policy-name.header.header-name

Si el JWS tiene una carga útil adjunta, se asigna la carga útil a la variable de flujo jws.policy-name.header.payload. En el caso de una carga útil independiente, payload está vacío. Consulta Variables de flujo para ver una lista completa de las variables definidas por esta política.

Referencia de elemento para Decodificar JWS

En la referencia de la política se describen los elementos y atributos de la política Decodificar JWS.

Atributos que se aplican al elemento de nivel superior

<DecodeJWS 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 <displayname></displayname> para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente en lenguaje natural.	N/A	Obligatorio
continueOnError	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado en la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política.	falso	Opcional
habilitada	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará, aunque siga adjunta a un flujo.	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 proxy de la interfaz de gestión 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

<Source>

<Source>JWS-variable</Source>

Si está presente, especifica la variable de flujo en la que la política espera encontrar el JWS que se va a decodificar.

Nota: De forma predeterminada, el JWS se obtiene de la variable request.header.authorization. En este caso, Apigee busca el JWS en el encabezado Authorization de la solicitud. Si envía el JWS en el encabezado Authorization, no es necesario que incluya el elemento Source en la política. Sin embargo, debe incluir Bearer en el encabezado de autorización. Por ejemplo, puedes transferir el JWS en el encabezado Authorization de esta forma:

curl -v http://52.200.92.187:9001/doctest-JWS/verify-rs256 -H "Authorization: Bearer <your JWS>"

Puede configurar la política para recuperar el JWS de una variable de parámetro de consulta o de formulario, o de cualquier otra variable. Si la variable no existe o si la política no puede encontrar el JWS, la política devuelve un error.

Predeterminado	request.header.authorization (Consulta la nota anterior para obtener información importante sobre el valor predeterminado).
Presencia	Opcional
Tipo	Cadena
Valores válidos	Nombre de una variable de flujo de Apigee

Flow variables

Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

Variable name	Description
decoded.header.name	The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
header.algorithm	The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid	The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more.
header.type	The header type value. See (Type) Header Parameter for more.
header.name	The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWS.
header-json	The header in JSON format.
payload	The JWS payload if the JWS has an attached payload. For a detached paylod, this variable is empty.
valid	In the case of VerifyJWS, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false. In the case of DecodeJWS, this variable is not set.

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de fallo	Estado de HTTP	Se produce cuando
steps.jws.FailedToDecode	401	La política no ha podido decodificar el JWS. Es posible que el JWS esté dañado.
steps.jws.FailedToResolveVariable	401	Se produce cuando no existe la variable de flujo especificada en el elemento <Source> de la política.
steps.jws.InvalidClaim	401	Si falta una reclamación o no coincide, o si falta un encabezado o no coincide.
steps.jws.InvalidJsonFormat	401	Se ha encontrado un JSON no válido en el encabezado de JWS.
steps.jws.InvalidJws	401	Este error se produce cuando no se puede verificar la firma JWS.
steps.jws.InvalidPayload	401	La carga útil de JWS no es válida.
steps.jws.InvalidSignature	401	<DetachedContent> se omite y el JWS tiene una carga útil de contenido independiente.
steps.jws.MissingPayload	401	Falta la carga útil de JWS.
steps.jws.NoAlgorithmFoundInHeader	401	Se produce cuando el JWS omite el encabezado del algoritmo.
steps.jws.UnknownException	401	Se ha producido una excepción desconocida.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nombre del error	Se produce 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.

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>