Política DecodeJWS

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

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.

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 administración de Edge aplica reglas restricciones, 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 Edge

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 payload, 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 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 Qué debes saber sobre los errores de políticas y Cómo solucionar 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.FailedToDecode 401 La política no pudo decodificar el JWS Es posible que el JWS esté dañado.
steps.jws.FailedToResolveVariable 401 Ocurre cuando la variable de flujo especificada en el elemento <Source> de la política no existe.
steps.jws.InvalidClaim 401 Porque falta un reclamo o un reclamo, o bien el encabezado o el encabezado no coinciden.
steps.jws.InvalidJsonFormat 401 Se encontró un JSON no válido en el encabezado JWS.
steps.jws.InvalidJws 401 Este error ocurre cuando falla la verificación de la firma del 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.MissingPayload 401 Falta la carga útil de JWS.
steps.jws.NoAlgorithmFoundInHeader 401 Ocurre cuando el JWS omite el encabezado del algoritmo.
steps.jws.UnknownException 401 Se produjo una excepción desconocida.

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.

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

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>