Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
Qué
Verifica la firma de un JWS recibido de clientes u otros sistemas. Esta política también extrae encabezados en variables de contexto para que las políticas o condiciones posteriores puedan examinar esos valores y tomar decisiones de autorización o de enrutamiento. Consulta la información general sobre las políticas de JWS y JWT para obtener una introducción detallada.
Si el JWS se verifica y es válido, se permite que la solicitud continúe. Si no se puede verificar la firma JWS o si el JWS no es válido debido a algún tipo de error, se detiene todo el procesamiento y se devuelve un error en la respuesta.
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.
Para obtener información sobre las partes de un JWS y cómo se cifran y firman, consulta el estándar RFC7515.
Vídeo
Vea un breve vídeo sobre cómo verificar la firma de un JWS. Aunque este vídeo se centra en la verificación de un JWT, muchos de los conceptos son los mismos para JWS.
Ejemplos
- Verificar un JWS adjunto firmado con el algoritmo HS256
- Verificar un JWS independiente firmado con el algoritmo RS256
Verificar un JWS adjunto firmado con el algoritmo HS256
Esta política de ejemplo verifica un JWS adjunto que se ha firmado con el algoritmo de cifrado HS256, HMAC
mediante una suma de comprobación SHA-256. El JWS se transfiere en la solicitud proxy mediante un parámetro de formulario llamado JWS
. La clave se incluye en una variable llamada private.secretkey
.
Un JWS adjunto contiene el encabezado, la carga útil y la firma codificados:
header.payload.signature
La configuración de la política incluye la información que necesita Apigee para decodificar y evaluar el JWS, como dónde encontrar el JWS (en una variable de flujo especificada en el elemento <Source>
), el algoritmo de firma necesario y dónde encontrar la clave secreta (almacenada en una variable de flujo de Apigee, que podría haberse obtenido del KVM de Apigee, por ejemplo).
<VerifyJWS name="JWS-Verify-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Algorithm>HS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> </VerifyJWS>
La política escribe su salida en variables de contexto para que las políticas o condiciones posteriores del proxy de API puedan examinar esos valores. Consulta Variables de flujo para ver una lista de las variables definidas por esta política.
Verificar un JWS independiente firmado con el algoritmo RS256
Esta política de ejemplo verifica un JWS independiente que se ha firmado con el algoritmo RS256. Para verificarlo, debes proporcionar la clave pública. El JWS se transfiere en la solicitud proxy mediante un parámetro de formulario llamado JWS
. La clave pública se incluye en una variable llamada public.publickey
.
Un JWS independiente omite la carga útil del JWS:
header..signature
Usted debe transferir la carga útil a la política VerifyJWS especificando el nombre de la variable que contiene la carga útil en el elemento
<DetachedContent>
. El contenido especificado en <DetachedContent>
debe estar en el formato original sin codificar que tenía cuando se creó la firma JWS.
<VerifyJWS name="JWS-Verify-RS256"> <DisplayName>JWS Verify RS256</DisplayName> <Algorithm>RS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <Value ref="public.publickey"/> </PublicKey> <DetachedContent>private.payload</DetachedContent> </VerifyJWS>
La política escribe su salida en variables de contexto para que las políticas o condiciones posteriores del proxy de API puedan examinar esos valores. Consulta Variables de flujo para ver una lista de las variables definidas por esta política.
Definir los elementos clave
Los elementos que se usan para especificar la clave que se utiliza para verificar el JWS dependen del algoritmo elegido, tal como se muestra en la siguiente tabla:
Algoritmo | elementos clave | |
---|---|---|
HS* |
<SecretKey> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key"/> </PublicKey> También puedes hacerlo de esta otra forma, si lo prefieres: <PublicKey> <JWKS ref="jwks_val_ref_or_url"/> </PublicKey> |
|
*Para obtener más información sobre los requisitos de las claves, consulta Acerca de los algoritmos de cifrado de firmas. |
Referencia de elemento
En la referencia de la política se describen los elementos y atributos de la política Verify JWS.
Nota: La configuración variará ligeramente en función del algoritmo de cifrado que utilices. Consulta los ejemplos para ver configuraciones de casos prácticos específicos.
SAtributos que se aplican al elemento de nivel superior
<VerifyJWS 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 proxies de la interfaz de usuario de Apigee 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 |
<Algorithm>
<Algorithm>HS256</Algorithm>
Especifica el algoritmo de cifrado para firmar el token. Los algoritmos RS*/PS*/ES* utilizan un par de claves pública y secreta, mientras que los algoritmos HS* utilizan un secreto compartido. Consulta también Acerca de los algoritmos de cifrado de firma.
Puede especificar varios valores separados por comas. Por ejemplo, "HS256, HS512" o "RS256, PS256". Sin embargo, no puedes combinar algoritmos HS* con otros ni algoritmos ES* con otros, ya que requieren un tipo de clave específico. Puedes combinar algoritmos RS* y PS*.
Predeterminado | N/A |
Presencia | Obligatorio |
Tipo | Cadena de valores separados por comas |
Valores válidos | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 y PS512 |
<AdditionalHeaders/Claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
Valida que el encabezado JWS contenga los pares nombre/valor de las reclamaciones adicionales especificados y que los valores de las reclamaciones confirmadas coincidan.
Una reclamación adicional usa un nombre que no es uno de los nombres de reclamación JWS estándar registrados. El valor de una reclamación adicional puede ser una cadena, un número, un valor booleano, un mapa o una matriz. Un mapa es simplemente un conjunto de pares nombre/valor. El valor de una reclamación de cualquiera de estos tipos se puede especificar explícitamente en la configuración de la política o indirectamente mediante una referencia a una variable de flujo.
Predeterminado | N/A |
Presencia | Opcional |
Tipo |
Cadena (valor predeterminado), número, booleano o mapa. Si no se especifica ningún tipo, se asigna el tipo String de forma predeterminada. |
Array | Asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false |
Valores válidos | Cualquier valor que quieras usar para una reclamación adicional. |
El elemento <Claim>
acepta estos atributos:
- name: (obligatorio) el nombre de la reclamación.
- ref: (opcional) Nombre de una variable de flujo. Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican tanto un atributo ref como un valor de reclamación explícito, el valor explícito será el predeterminado y se usará si la variable de flujo a la que se hace referencia no se resuelve.
- type: (opcional) uno de los siguientes valores: string (valor predeterminado), number, boolean o map.
- array: (opcional) asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false.
<DetachedContent>
<DetachedContent>variable-name-here</DetachedContent>
Un JWS generado con una carga útil de contenido tiene el siguiente formato:
header.payload.signature
Si usas la política GenerateJWS para crear una carga útil independiente, el JWS generado omite la carga útil y tiene el siguiente formato:
header..signature
En el caso de una carga útil independiente, debes pasar la carga útil a la política VerifyJWS mediante el elemento <DetachedContent>
. La carga útil de contenido especificada debe estar en el formato original sin codificar que tenía cuando se creó la firma JWS.
La política genera un error cuando:
<DetachedContent>
se especifica cuando el JWS no contiene una carga útil de contenido independiente (el código de error essteps.jws.ContentIsNotDetached
).<DetachedContent>
se omite y el JWS tiene una carga útil de contenido independiente (el código de error essteps.jws.InvalidSignature
).
Predeterminado | N/A |
Presencia | Opcional |
Tipo | Referencia de variable |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Asigna el valor false si quieres que la política genere un error cuando no se incluya en el elemento <KnownHeaders>
ningún encabezado de la lista del encabezado crit del JWS.
Asigna el valor true para que la política VerifyJWS ignore el encabezado crit.
Uno de los motivos para asignar el valor "true" a este elemento es si te encuentras en un entorno de pruebas y no quieres que la política falle por falta de un encabezado.
Predeterminado | falso |
Presencia | Opcional |
Tipo | Booleano |
Valores válidos | verdadero o falso |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Asigna el valor false si quieres que la política genere un error cuando no se pueda resolver ninguna variable de referencia especificada en la política. Se define como true para tratar cualquier variable que no se pueda resolver como una cadena vacía (nula).
Predeterminado | falso |
Presencia | Opcional |
Tipo | Booleano |
Valores válidos | verdadero o falso |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
La política GenerateJWS usa el elemento <CriticalHeaders>
para rellenar el encabezado crit de un token. Por ejemplo:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
La política VerifyJWS examina la cabecera crit del JWS, si existe, y, por cada elemento de la lista, comprueba que el elemento <KnownHeaders>
también incluya esa cabecera. El elemento <KnownHeaders>
puede contener un superconjunto de los elementos que se indican en crit.
Solo es necesario que todas las cabeceras que se indican en crit se incluyan en el elemento <KnownHeaders>
. Si la política encuentra alguna cabecera en crit
que no esté también en <KnownHeaders>
, la política VerifyJWS fallará.
También puedes configurar la política VerifyJWS para que ignore el encabezado crit
asignando el valor true
al elemento <IgnoreCriticalHeaders>
.
Predeterminado | N/A |
Presencia | Opcional |
Tipo | Matriz de cadenas separadas por comas |
Valores válidos | Una matriz o el nombre de una variable que contenga la matriz. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
Especifica un valor en formato JWKS (RFC 7517) que contiene un conjunto de claves públicas. Úsalo solo cuando el algoritmo sea RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 o ES512.
Si el JWS entrante tiene un ID de clave que está presente en el conjunto de JWKS, la política usará la clave pública correcta para verificar la firma del JWS. Para obtener más información sobre esta función, consulta Usar un conjunto de claves web JSON (JWKS) para verificar un JWS.
Si obtiene el valor de una URL pública, Apigee almacena en caché el JWKS durante un periodo de 300 segundos. Cuando caduca la caché, Apigee vuelve a obtener el JWKS.
Predeterminado | N/A |
Presencia | Para verificar un JWS con un algoritmo RSA, debe usar el elemento JWKS o el elemento Value. |
Tipo | Cadena |
Valores válidos | Una variable de flujo, un valor de cadena o una URL. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickey"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2 ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
Especifica la clave pública que se usa para verificar la firma del JWS. Usa el atributo ref para transferir la clave en una variable de flujo o especificar la clave codificada en PEM directamente. Úsalo solo cuando el algoritmo sea RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 o ES512.
Predeterminado | N/A |
Presencia | Para verificar un JWS firmado con un algoritmo RSA, debes usar los elementos JWKS o Value. |
Tipo | Cadena |
Valores válidos | Una variable de flujo o una cadena. |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Value ref="private.your-variable-name"/> </SecretKey>
Especifica la clave secreta que se debe usar al verificar un JWS que usa un algoritmo simétrico (HS*), como HS256, HS384 o HS512.
Este elemento es opcional. Sin embargo, debe incluir exactamente uno de los elementos <PublicKey>
o <SecretKey>
.
Usa el elemento <PublicKey>
cuando verifiques un JWS cuyo algoritmo sea RS*, PS* o ES*, y usa el elemento <SecretKey>
cuando verifiques un JWS cuyo algoritmo sea HS*.
Hijos de <SecretKey>
En la siguiente tabla se describen los elementos secundarios y los atributos de <SecretKey>
:
Hijo/a | Presencia | Descripción |
---|---|---|
codificación (atributo) | Opcional | Especifica cómo se codifica la clave en la variable a la que se hace referencia. De forma predeterminada, si no se incluye el atributo <SecretKey encoding="base64" > <Value ref="private.secretkey"/> </SecretKey> En el ejemplo anterior, como la codificación es |
Valor (elemento) | Obligatorio | Una clave secreta codificada. Especifica la clave secreta que se usará para verificar la carga útil. Utilice el atributo <SecretKey> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee aplica una longitud mínima de clave para los algoritmos HS256, HS384 y HS512. La longitud mínima de la clave de HS256 es de 32 bytes, la de HS384 es de 48 bytes y la de HS512 es de 64 bytes. Si se usa una clave con una seguridad inferior, se produce un error de tiempo de ejecución. |
<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 verificar.
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. |
<Type>
<Type>type-string-here</Type>
Elemento opcional cuyo único valor permitido es Signed
, que especifica que la política verifica un JWS firmado. <Type>
se proporciona
solo para que coincida con el elemento correspondiente de las políticas GenerateJWT y VerifyJWT (donde
puede adoptar cualquiera de los valores Signed
o Encrypted
).
Predeterminado | N/A |
Presencia | Opcional |
Tipo | Cadena |
Valor válido | Signed |
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.AlgorithmInTokenNotPresentInConfiguration |
401 |
Se produce cuando la política de verificación tiene varios algoritmos. |
steps.jws.AlgorithmMismatch |
401 |
El algoritmo especificado en el encabezado de la política Generate no coincide con el esperado en la política Verify . Los algoritmos especificados deben coincidir. |
steps.jws.ContentIsNotDetached |
401 |
<DetachedContent> se especifica cuando el JWS no contiene una carga útil de contenido desconectado. |
steps.jws.FailedToDecode |
401 |
La política no pudo decodificar el JWS. Es posible que el JWS esté dañado. |
steps.jws.InsufficientKeyLength |
401 |
En el caso de una clave de menos de 32 bytes para el algoritmo HS256 |
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.InvalidCurve |
401 |
La curva especificada por la clave no es válida para el algoritmo de curva elíptica. |
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.KeyIdMissing |
401 |
La política Verify usa un JWKS como fuente para las claves públicas, pero el JWT firmado no incluye una propiedad kid en el encabezado. |
steps.jws.KeyParsingFailed |
401 |
No se pudo analizar la clave pública a partir de la información de claves determinada. |
steps.jws.MissingPayload |
401 |
Falta la carga útil JWS. |
steps.jws.NoAlgorithmFoundInHeader |
401 |
Ocurre cuando el JWS omite el encabezado del algoritmo. |
steps.jws.NoMatchingPublicKey |
401 |
La política Verify usa un JWKS como fuente para claves públicas, pero kid en el JWS firmado no aparece en el JWKS. |
steps.jws.UnhandledCriticalHeader |
401 |
Un encabezado que encontró la política de verificación de JWS en el encabezado crit no aparece en KnownHeaders . |
steps.jws.UnknownException |
401 |
Se produjo una excepción desconocida. |
steps.jws.WrongKeyType |
401 |
El tipo de clave especificado es incorrecto. Por ejemplo, si especificas una clave RSA para un algoritmo de curva elíptica o una clave de curva para un algoritmo de RSA. |
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 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>