Política VerifyJWS

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

Consulta la documentación de Apigee Edge.

Icono de política

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

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.

S

Atributos 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 <displayname></displayname> para etiquetar la política en el editor de proxies de la interfaz de usuario de Apigee 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 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 es steps.jws.ContentIsNotDetached).
  • <DetachedContent> se omite y el JWS tiene una carga útil de contenido independiente (el código de error es steps.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 encoding, la codificación de la clave se trata como UTF-8. Los valores válidos del atributo son: hex, base16, base64 o base64url. Los valores de codificación hexadecimal y base16 son sinónimos.

<SecretKey encoding="base64" >
  <Value ref="private.secretkey"/>
</SecretKey>

En el ejemplo anterior, como la codificación es base64, si el contenido de la variable private.secretkey es SUxvdmVBUElz, la clave se decodificará como un conjunto de 9 bytes, que en hexadecimal será 49 4c 6f 76 65 41 50 49 73.

Valor (elemento) Obligatorio

Una clave secreta codificada. Especifica la clave secreta que se usará para verificar la carga útil. Utilice el atributo ref para proporcionar la clave indirectamente a través de una variable, como private.secret-key .

<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 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.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 independiente.
steps.jws.FailedToDecode 401 La política no ha podido decodificar el JWS. Es posible que el JWS esté dañado.
steps.jws.InsufficientKeyLength 401 Para una clave de menos de 32 bytes para el algoritmo HS256
steps.jws.InvalidClaim 401 Si falta una reclamación o no coincide, o si falta un encabezado o no coincide.
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 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.KeyIdMissing 401 La política Verify usa un JWKS como fuente de claves públicas, pero el JWS firmado no incluye una propiedad kid en el encabezado.
steps.jws.KeyParsingFailed 401 No se ha podido analizar la clave pública a partir de la información de clave proporcionada.
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.NoMatchingPublicKey 401 La política Verify usa un JWKS como fuente de claves públicas, pero el kid del JWS firmado no aparece en el JWKS.
steps.jws.UnhandledCriticalHeader 401 Un encabezado encontrado por la política Verify JWS en el encabezado crit no aparece en KnownHeaders.
steps.jws.UnknownException 401 Se ha producido una excepción desconocida.
steps.jws.WrongKeyType 401 Se ha especificado un tipo de clave incorrecto. Por ejemplo, si especificas una clave RSA para un algoritmo de curva elíptica o una clave de curva para un algoritmo RSA.

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.

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 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>