Política DecodeJWS

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

Consulta la documentación de Apigee Edge.

ícono de política

Qué

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

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

header.payload.signature

O bien, el JWS puede omitir la carga útil, llamada carga útil desconectada, y tener el siguiente formato:

header..signature

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

Consulta la descripción general de las políticas de JWS y JWT para obtener una introducción detallada y una descripción general del formato de un JWS.

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 breve video para aprender cómo decodificar un JWT. Si bien este video es específico de la verificación de un JWT, muchos de los conceptos son los mismos para JWS.

Muestra: Decodifica 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 o rechazado. 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 en la parte del encabezado del JWS, la política establece una variable de flujo denominada:

jws.policy-name.header.header-name

Si el JWS tiene una carga útil adjunta, establece la variable de flujo jws.policy-name.header.payload en la carga útil. Para una carga útil separada, payload está vacío. Consulta Variables de flujo para obtener completa una lista de las variables que establece esta política.

Referencia del elemento para decodificar JWS

La referencia de política describe los elementos y atributos de la política de decodificación de 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 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 <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

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

Predeterminada request.header.authorization (consulta la nota anterior para obtener información importante sobre el valor predeterminado).
Presencia Opcional
Tipo String
Valores válidos Un nombre de variable de flujo de Apigee.

Variables de flujo

Si se ejecuta de forma correcta, las políticas Verificación de JWS y Decodificación de JWS establecen variables de contexto de acuerdo con este patrón:

jws.{policy_name}.{variable_name}

Por ejemplo, si el nombre de la política es verify-jws, la política almacenará el algoritmo especificado en el JWS a esta variable de contexto: jws.verify-jws.header.algorithm

Nombre de la variable Descripción
decoded.header.name El valor JSON analizable de un encabezado en la carga útil. Se configura una variable para cada encabezado de la carga útil. Si bien también puedes usar las variables de flujo header.name, esta es la variable recomendada para acceder a un encabezado.
header.algorithm El algoritmo de firma que se usa en el JWS. Por ejemplo, RS256, HS384, etcétera. Consulta Parámetro de encabezado (algoritmo) para obtener más información.
header.kid El ID de clave, si se agregó cuando se generó el JWS. También puedes consultar “Usa un conjunto de claves web de JSON (JWKS)” en la descripción general de las políticas de JWT y JWS para verificar una JWS. Consulta el Parámetro de encabezado (ID de clave) para obtener más información.
header.type El valor del tipo de encabezado. Consulta Parámetro de encabezado (tipo) para obtener más información.
header.name El valor del encabezado con nombre (estándar o adicional). Uno de estos se establecerá para cada encabezado adicional en la parte del encabezado de JWS.
header-json El encabezado en formato JSON
payload La carga útil de JWS si el JWS tiene una carga útil adjunta. Para una carga de trabajo desconectada, esta variable está vacía.
valid En el caso de VerifyJWS, esta variable será verdadera cuando se verifique la firma y la hora actual será anterior al vencimiento del token y, si están presentes, después del valor notBefore del token. De lo contrario, es falso.

En el caso de DecodeJWS, esta variable no está configurada.

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.FailedToDecode 401 The policy was unable to decode the JWS. The JWS is possibly corrupted.
steps.jws.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidJws 401 This error occurs when the JWS signature verification fails.
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.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.UnknownException 401 An unknown exception occurred.

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.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 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>