Estás viendo la documentación de Apigee Edge.
Ve a la
Documentación de Apigee X. información
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.
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 adjunto firmado con el algoritmo HS256
- Verifica un JWS desconectado firmado con el algoritmo RS256
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 Edge 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 Edge, que podría
se recuperaron del KVM de Edge, 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.
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 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 |
<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 essteps.jws.ContentIsNotDetached
).<DetachedContent>
se omite y la JWS tiene una carga útil de contenido desconectado (el código de fragmento essteps.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, Edge almacena en caché el JWKS durante un período de 300 segundos. Cuando vence la caché, Edge recupera el JWKS otra vez.
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/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
Proporciona la clave secreta usada para verificar o firmar tokens con un algoritmo HMAC. Úsalo solo cuando el algoritmo sea uno de HS256, HS384, HS512. Usa el atributo ref para pasar la clave en una variable de flujo.
Predeterminada | N/A |
Presencia | Obligatorio para los algoritmos HMAC. |
Tipo | String |
Valores válidos |
Una variable de flujo que hace referencia a una string.
Nota: Si es una variable de flujo, debe tener el prefijo “private”. Por ejemplo: |
<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 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.AlgorithmInTokenNotPresentInConfiguration |
401 | Se produce cuando la política de verificación tiene varios algoritmos. |
steps.jws.AlgorithmMismatch |
401 | El algoritmo que especifica la política Generar no coincidió con el esperado en la política Verificar. Los algoritmos especificados deben coincidir. |
steps.jws.ContentIsNotDetached |
401 | <DetachedContent> se especifica cuando el JWS no contiene una carga útil de contenido separado. |
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 | Porque falta un reclamo o un reclamo, o bien el encabezado o el encabezado no coinciden. |
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 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.KeyIdMissing |
401 | La política Verificar usa un JWKS como fuente para las claves públicas, pero el JWS 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 clave proporcionada. |
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.NoMatchingPublicKey |
401 | La política de verificación usa un JWKS como fuente para claves públicas, pero la propiedad 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 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>