Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
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 |
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 |
falso | Opcional |
habilitada |
Asigna el valor true para aplicar la política.
Selecciona |
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 la verificación se realiza correctamente, las políticas Verificar JWS y Decodificar JWS definen variables de contexto según 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 en esta variable de contexto:
jws.verify-jws.header.algorithm
Nombre de variable | Descripción |
---|---|
decoded.header.name |
Valor analizable de JSON de un encabezado de la carga útil. Se define una variable para cada encabezado de la carga útil. Aunque 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 usado en el JWS. Por ejemplo, RS256, HS384, etc. Para obtener más información, consulta Parámetro de encabezado(algoritmo). |
header.kid |
El ID de clave, si se ha añadido al generar el JWS. Consulta también "Usar un conjunto de claves web JSON (JWKS)" en Información general sobre políticas de JWT y JWS para verificar un JWS. Consulte más información sobre el parámetro de encabezado(ID de clave). |
header.type |
Valor del tipo de encabezado. Consulta Parámetro de encabezado(Type) para obtener más información. |
header.name |
El valor del encabezado en cuestión (estándar o adicional). Se definirá uno de estos para cada encabezado adicional de la parte de encabezado del JWS. |
header-json |
El encabezado en formato JSON. |
payload |
La carga útil de JWS si el JWS tiene una carga útil adjunta. En el caso de una carga útil independiente, esta variable está vacía. |
valid |
En el caso de VerifyJWS, esta variable será true cuando se verifique la firma y la hora actual sea anterior a la fecha de vencimiento del token y posterior al valor notBefore del token, si están presentes. En caso contrario, devuelve el valor false.
En el caso de DecodeJWS, esta variable no se define. |
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 . |
|
Otros posibles errores de implementación. |
Variables de error
Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.
Variables | Dónde | Ejemplo |
---|---|---|
fault.name="fault_name" |
fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error. | fault.name Matches "TokenExpired" |
JWS.failed |
Todas las políticas de JWS definen la misma variable en caso de fallo. | jws.JWS-Policy.failed = true |
Ejemplo de respuesta de error
Para gestionar los errores, la práctica recomendada es interceptar la parte errorcode
de la respuesta de error. No te fíes del texto de faultstring
, ya que podría cambiar.
Regla de fallo de ejemplo
<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>