Política DecodeJWS

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

Consulta la documentación de Apigee Edge.

Icono de política

Qué

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 un JWS antes de verificar la firma del 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.

Vídeo

Vea un breve vídeo para aprender a decodificar un JWT. Aunque este vídeo se centra en los JWTs, muchos de los conceptos son los mismos para los JWSs.

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 de Decode 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 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 de 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.

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

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

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 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 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.InvalidJsonFormat 401 Se encontró un archivo JSON que no es 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 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 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 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>