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 |
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 |
falso | Opcional |
habilitado | Configúralo como true para aplicar la política.Configúralo como |
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 |
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 útil 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 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. |
|
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>