Política VerifyJWS

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

Consulta la documentación de Apigee Edge.

ícono de política

Qué

Verifica la firma en un JWS que recibe de clientes o de 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 a fin de tomar decisiones de autorización o enrutamiento. Consulta la descripción general de las políticas de JWS y JWT para obtener una introducción detallada.

Si el JWS está verificado y es válido, la solicitud puede continuar. Si la firma JWS no se puede verificar o si el JWS no es válida debido a algún tipo de error, se detiene todo el procesamiento y se muestra un error en la respuesta.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Para obtener información sobre las partes de un JWS y cómo se encriptan y firman, consulta RFC7515.

Video

Mira un breve video para aprender cómo verificar la firma en un JWS. Si bien este video es específico de la verificación de un JWT, muchos de los conceptos son los mismos para JWS.

Ejemplos

Verifica un JWS conectado con el algoritmo HS256

En esta política de ejemplo, se verifica una JWS adjunta que se firmó con el algoritmo de encriptación HS256, HMAC mediante una suma de verificación SHA-256. El JWS se pasa en la solicitud de proxy mediante un parámetro de formato llamado JWS. La clave se encuentra en una variable llamada private.secretkey.

Un JWS adjunto contiene el encabezado codificado, la carga útil y la firma:

header.payload.signature

La configuración de la política incluye la información que Apigee necesita 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 requerido, y dónde encontrar la clave secreta (almacenada en una variable de flujo de Apigee, que se podría recuperar de la 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 resultado en variables de contexto para que las políticas o condiciones posteriores en el proxy de API puedan examinar esos valores. Consulta Variables de flujo para obtener una lista de las variables que establece esta política.

Verifica un JWS desconectado firmado con el algoritmo RS256

Esta política de ejemplo verifica un JWS desconectado que se firmó con el algoritmo RS256. Para verificarlo, debes proporcionar la clave pública. El JWT se pasa en la solicitud de proxy mediante un parámetro de formato llamado JWS. La clave pública se encuentra en una variable llamada public.publickey.

Un JWS desconectado omite la carga útil del JWS:

header..signature

Depende de ti pasar la carga útil a la política VerifyJWS y especificar el nombre de variable que contiene la carga útil para el elemento <DetachedContent>. El contenido especificado en <DetachedContent> debe tener el formato original sin codificación, 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 resultado en variables de contexto para que las políticas o condiciones posteriores en el proxy de API puedan examinar esos valores. Consulta Variables de flujo para obtener una lista de las variables que establece esta política.

Configura los elementos clave

Los elementos que uses para especificar la clave usada con el fin de verificar el JWS dependerá del algoritmo elegido, 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>

o:


<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>
* Para obtener más información sobre los requisitos de las claves, consulta Información sobre los algoritmos de encriptación de firmas.

Referencia del elemento

La referencia de política describe los elementos y atributos de la política de verificación de JWS.

Nota: La configuración variará en función del algoritmo de encriptación que uses. Consulta Muestras para ver ejemplos que demuestran configuraciones específicas para casos de uso 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 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 Apigee aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos.

De forma opcional, usa el elemento <displayname></displayname> para etiquetar la política en el editor de proxy de IU de Apigee con un nombre de lenguaje natural diferente.

 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 true para continuar con la ejecución del flujo incluso después de que una política falle.

 falso Opcional
habilitado Configúralo como true para aplicar la política.

Configúralo como false para “desactivar” la política. La política no se aplicará, incluso si permanece conectada a un flujo.

 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 Apigee con un nombre diferente y con lenguaje natural.

Configuración predeterminada Si omites este elemento, se usa el valor del atributo de nombre de la política.
Presencia Opcional
Tipo String

<Algorithm>

<Algorithm>HS256</Algorithm>

Especifica el algoritmo de encriptación para firmar el token. Los algoritmos RS*/PS*/ES* emplean un par de claves públicas y secretas, mientras que los algoritmos HS* usan un secreto compartido. Consulta también Información sobre los algoritmos de encriptación de firmas.

Puedes especificar varios valores separados por comas. Por ejemplo, “HS256, HS512” o “RS256, PS256”. Sin embargo, no se pueden combinar algoritmos de HS* con ningún otro algoritmo o algoritmos ES* con el resto de los casos que requieren un tipo de clave específico. Puedes combinar los algoritmos de RS* y PS*.

Valor predeterminado N/A
Presencia Obligatorio
Tipo String de valores separados por comas
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, 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 de valor o nombres de reclamos adicionales especificados y que coincidan los valores de la reclamación confirmada.

Un reclamo adicional usa un nombre que no es uno de los nombres de reclamación JWS estándar y registrados. El valor de una reclamación adicional puede ser una string, un número, un valor booleano, un mapa o un arreglo. Un mapa es tan solo un conjunto de pares nombre-valor. El valor de una reclamación de cualquiera de estos tipos se puede especificar de manera explícita en la configuración de la política, o bien en forma indirecta a través de una referencia a una variable de flujo.

Valor predeterminado N/A
Presencia Opcional
Tipo

String (predeterminada), número, booleano o mapa.

El tipo predeterminado es String si no se especifica un tipo.
Matriz Configúralo en true para indicar si el valor es un arreglo de tipos. Valor predeterminado: false
Valores válidos Cualquier valor que desees usar para una reclamación adicional.

El elemento <Claim> incluye los siguientes atributos:

  • name: El nombre del reclamo (obligatorio).
  • ref: El nombre de una variable de flujo (opcional). Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican un atributo ref y un valor de reclamación explícito, el valor explícito es el predeterminado y se usa si la variable de flujo a la que se hace referencia no se resuelve.
  • type: (Opcional) uno de los siguientes: string, (predeterminado), número, booleano o mapa.
  • arreglo: (Opcional) Establece en true para indicar si el valor es un arreglo 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 desconectada, el JWS generado omite la carga útil y tiene el siguiente formato:

header..signature

Para una carga útil desconectada, depende de ti transferir la carga útil a la política VerifyJWS mediante el elemento <DetachedContent>. La carga útil del contenido especificada debe tener el formato original sin codificación, cuando se creó la firma JWS.

La política muestra un error cuando ocurre lo siguiente:

  • <DetachedContent> se especifica cuando el JWS no contiene una carga útil de contenido desconectado (el código de fragmento es steps.jws.ContentIsNotDetached).
  • <DetachedContent> se omite y la JWS tiene una carga útil de contenido desconectado (el código de fragmento es steps.jws.InvalidSignature).
Predeterminada N/A
Presencia Opcional
Tipo Referencia de las variables

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Configúralo como falso si deseas que la política genere un error cuando algún encabezado indicado en el encabezado crit del JWS no aparezca en el elemento <KnownHeaders>. Se establece en verdadero para que la política VerifyJWS ignore el encabezado crit.

Una razón para configurar este elemento como verdadero es si estás en un entorno de pruebas y no quieres que la política falle debido a que falta un encabezado.

Predeterminada falso
Presencia Opcional
Tipo Booleano
Valores válidos True o False

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Configúralo como false si deseas que la política muestre un error cuando no se pueda resolver cualquier variable a la que se especifica en la política. Se establece como true para tratar cualquier variable no recuperable como una string vacía (null).

Valor predeterminado falso
Presencia Opcional
Tipo Booleano
Valores válidos True o False

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

La política GenerateJWS usa el elemento <CriticalHeaders> para propagar el encabezado crit en un token. Por ejemplo:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

La política VerifyJWS examina el encabezado crit en el JWS, si existe, y para cada elemento enumerado, comprueba que el elemento <KnownHeaders> también enumere ese encabezado. El elemento <KnownHeaders> puede contener un superconjunto de los elementos que aparecen en crit. Solo es necesario que todos los encabezados enumerados en crit se enumeren en el elemento <KnownHeaders>. Cualquier encabezado que la política encuentre en crit que no esté incluido en <KnownHeaders> provoca que la política VerifyJWS falle.

De forma opcional, puedes configurar la política VerifyJWS para ignorar el encabezado crit si estableces el elemento <IgnoreCriticalHeaders> en true.

Predeterminada N/A
Presencia Opcional
Tipo Arreglo de strings separadas por comas
Valores válidos Un arreglo o el nombre de una variable que contiene el arreglo.

<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. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/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 de JWS. Para obtener detalles sobre esta característica, consulta Usa un conjunto de claves web JSON (JWKS) para verificar una JWS.

Si recuperas el valor de una URL pública, Apigee almacena en caché el JWKS durante un período de 300 segundos. Cuando vence la caché, Apigee recupera los JWKS de nuevo.

Valor predeterminado N/A
Presencia Para verificar un JWS con un algoritmo de RSA, debes usar el elemento JWKS o valor.
Tipo String
Valores válidos Una variable de flujo, un valor de string 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 en el JWS. Usa el atributo ref para pasar la clave en una variable de flujo o especifica la clave codificada de PEM directamente. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Valor predeterminado N/A
Presencia Para verificar un JWS firmado con un algoritmo de RSA, debes usar los elementos JWKS o valor.
Tipo String
Valores válidos Una string o variable de flujo.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Value ref="private.your-variable-name"/>
</SecretKey>

Especifica la clave secreta que se usará cuando se verifique un JWS que use un algoritmo simétrico (HS*), que puede ser HS256, HS384 o HS512.

Este elemento es opcional. Sin embargo, debes incluir exactamente uno de los elementos <PublicKey> o <SecretKey>. Usa el elemento <PublicKey> cuando verifiques un JWS para el que el algoritmo sea RS*, PS* o ES*, y usa el elemento <SecretKey> cuando verifiques un JWS para el que el algoritmo es HS*

Secundarios de <SecretKey>

En la siguiente tabla, se proporciona una descripción de los elementos secundarios y los atributos de <SecretKey>:

Secundario 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, cuando no hay un atributo encoding presente, la codificación de la clave se trata como UTF-8. Estos son los valores válidos para el atributo: hex, base16, base64 o base64url. Los valores de codificación hex y base16 son sinónimos.


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

En el ejemplo anterior, debido a que 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 hex 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. Usa el atributo ref para proporcionar la clave de forma indirecta a través de una variable, como private.secret-key.


<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee aplica una seguridad de clave mínima para los algoritmos HS256/HS384/HS512. La longitud mínima de la clave de HS256 es de 32 bytes, para HS384 es de 48 bytes, y para HS512 es de 64 bytes. El uso de una clave de baja intensidad provoca un error en el entorno 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 verificará.

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

<Type>

<Type>type-string-here</Type>

Elemento opcional cuyo único valor permitido es Signed y especifica que la política verifica un JWS firmado. <Type> se proporciona solo para hacer coincidir el elemento correspondiente para las políticas GenerateJWT y VerifyJWT (en las que puede tomar cualquiera de los valores Signed o Encrypted).

Valor predeterminado N/A
Presencia Opcional
Tipo String
Valor válido Signed

Flow variables

Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

Variable name Description
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
header.algorithm The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more.
header.type The header type value. See (Type) Header Parameter for more.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWS.
header-json The header in JSON format.
payload The JWS payload if the JWS has an attached payload. For a detached paylod, this variable is empty.
valid In the case of VerifyJWS, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWS, this variable is not set.

Referencia de errores

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jws.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms
steps.jws.AlgorithmMismatch 401 The algorithm specified in the header by the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jws.ContentIsNotDetached 401 <DetachedContent> is specified when the JWS does not contain a detached content payload.
steps.jws.FailedToDecode 401 The policy was unable to decode the JWS. The JWS is possibly corrupted.
steps.jws.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidJws 401 This error occurs when the JWS signature verification fails.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not include a kid property in the header.
steps.jws.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWS is not listed in the JWKS.
steps.jws.UnhandledCriticalHeader 401 A header found by the Verify JWS policy in the crit header is not listed in KnownHeaders.
steps.jws.UnknownException 401 An unknown exception occurred.
steps.jws.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when
InvalidAlgorithm The only valid values are: 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

 Other possible deployment errors.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "TokenExpired"
JWS.failed All JWS policies set the same variable in the case of a failure. jws.JWS-Policy.failed = true

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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