Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de Apigee Edge.
Qué
Verifica un JWT firmado o desencripta y verifica un JWT encriptado recibido de clientes o de otros sistemas. Esta política también extrae las reclamaciones en variables de contexto para que las políticas o condiciones posteriores puedan examinar esos valores para 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.
Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.
Cuando se ejecuta esta política, en el caso de un JWT firmado, Apigee verifica la firma del JWT con la clave de verificación proporcionada. En el caso de un JWT encriptado, Apigee desencripta el JWT a través de la clave de desencriptación. En cualquier caso, Apigee verifica que el JWT sea válido según los tiempos de vencimiento y “no antes de” si están presentes. De forma opcional, la política también puede verificar los valores de reclamaciones específicas en el JWT, como el asunto, la entidad emisora, el público o el valor de las reclamaciones adicionales.
Si el JWT se verifica y es válido, todas las reclamaciones incluidas en el JWT se extraen en variables de contexto para que las usen las condiciones o políticas posteriores, y se permite continuar con la solicitud. Si la firma JWT no se puede verificar o si el JWT no es válido debido a una de las marcas de tiempo, se detiene todo el procesamiento y se devuelve un error en la respuesta.
Para obtener información sobre las partes de un JWT y cómo se encriptan y firman, consulta RFC7519.
Cómo
La política que verifica un JWT firmado o encriptado depende del elemento que usas para especificar el algoritmo que verifica el JWT:
- Si usas el elemento
<Algorithm>
, la política verifica un JWT firmado. - Si usas el elemento
<Algorithms>
, la política verifica un JWT encriptado.
Video
Mira un breve video para aprender a verificar la firma en un JWT.
Verifica un JWT firmado
En esta sección, se explica cómo verificar un JWT firmado. Para un JWT firmado, usa el elemento <Algorithm>
para especificar el algoritmo para firmar la clave.
Muestras de un JWT firmado
En los siguientes ejemplos, se ilustra cómo verificar un JWT firmado.
Algoritmo HS256
En esta política de ejemplo, se verifica un JWT firmado con el algoritmo de encriptación HS256, HMAC a través de una suma de verificación SHA-256. El JWT se pasa en la solicitud de proxy a través de un parámetro de formato llamado jwt
. La clave se encuentra en una variable llamada private.secretkey
.
Mira el video anterior para ver un ejemplo completo, que incluye cómo realizar una solicitud a la política.
La configuración de la política incluye la información que Apigee necesita decodificar y evaluar el JWT, por ejemplo, dónde encontrar el JWT (en una variable de flujo especificada en el elemento de origen), el algoritmo de firma necesario, en el que se encuentra la clave secreta (almacenada en una variable de flujo de Apigee, que se podría recuperar de la KVM de Apigee, por ejemplo) y un conjunto de reclamaciones requeridas y sus valores.
<VerifyJWT name="JWT-Verify-HS256"> <DisplayName>JWT Verify HS256</DisplayName> <Algorithm>HS256</Algorithm> <Source>request.formparam.jwt</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey encoding="base64"> <Value ref="private.secretkey"/> </SecretKey> <Subject>monty-pythons-flying-circus</Subject> <Issuer>urn://apigee-edge-JWT-policy-test</Issuer> <Audience>fans</Audience> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> </VerifyJWT>
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.
Algoritmo RS256
En esta política de ejemplo, se verifica un JWT firmado con el algoritmo RS256. Para verificarlo, debes proporcionar la clave pública. El JWT se pasa en la solicitud de proxy a través de un parámetro de formato llamado jwt
. La clave pública se encuentra en una variable llamada public.publickey
.
Mira el video anterior para ver un ejemplo completo, que incluye cómo realizar una solicitud a la política.
Consulta la referencia del elemento para obtener detalles sobre los requisitos y las opciones de cada elemento en esta política de muestra.
<VerifyJWT name="JWT-Verify-RS256"> <Algorithm>RS256</Algorithm> <Source>request.formparam.jwt</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <Value ref="public.publickey"/> </PublicKey> <Subject>apigee-seattle-hatrack-montage</Subject> <Issuer>urn://apigee-edge-JWT-policy-test</Issuer> <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> </VerifyJWT>
Para la configuración anterior, un JWT con este encabezado…
{ "typ" : "JWT", "alg" : "RS256" }
Y esta carga útil…
{ "sub" : "apigee-seattle-hatrack-montage", "iss" : "urn://apigee-edge-JWT-policy-test", "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a", "show": "And now for something completely different." }
…se considerará como válida, si se puede verificar la firma con la clave pública proporcionada.
Un JWT con el mismo encabezado, pero con esta carga útil…
{ "sub" : "monty-pythons-flying-circus", "iss" : "urn://apigee-edge-JWT-policy-test", "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a", "show": "And now for something completely different." }
…Se determinará que no es válida, incluso si la firma puede verificarse, ya que la reclamación “sub” incluida en el JWT no coincide con el valor requerido del elemento “Subject” como se especifica en la configuración de política.
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.
En los ejemplos anteriores, se usa el elemento <Algorithm>
, por lo que verifican un JWT firmado. El elemento <PrivateKey>
especifica la clave usada para firmar el JWT. También hay otros elementos clave. El que uses depende del algoritmo que especifica el valor de <Algorithm>
, como se describe en la sección siguiente.
Configura los elementos clave para verificar un JWT firmado
En los siguientes elementos, se especifica la clave que se usa para verificar un JWT firmado:
El elemento que uses depende del algoritmo elegido, como se muestra en la siguiente tabla:
Algoritmo | Elementos clave | |
---|---|---|
HS* |
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key_or_value"/> </PublicKey> o: <PublicKey> <Certificate ref="signed_cert_val_ref"/> </PublicKey> o: <PublicKey> <JWKS ref="jwks_val_or_ref"/> </PublicKey> |
|
* Para obtener más información sobre los requisitos de las claves, consulta Información sobre los algoritmos de encriptación de firmas. |
Verifica un JWT encriptado
En esta sección, se explica cómo verificar un JWT encriptado. En el caso de un JWT encriptado, usa el elemento <Algorithms>
para especificar los algoritmos de firma de clave y contenido.
Muestra de un JWT encriptado
En el siguiente ejemplo, se muestra cómo verificar un JWT encriptado (con <Type>
configurado como Encrypted
), en el que se ilustra lo siguiente:
- La clave se encripta con el algoritmo RSA-OAEP-256.
- El contenido se encripta con el algoritmo A128GCM.
<VerifyJWT name="vjwt-1"> <Algorithms> <Key>RSA-OAEP-256</Key> <Content>A128GCM</Content> </Algorithms> <Type>Encrypted</Type> <PrivateKey> <Value ref="private.rsa_privatekey"/> </PrivateKey> <Subject>subject@example.com</Subject> <Issuer>urn://apigee</Issuer> <AdditionalHeaders> <Claim name="moniker">Harvey</Claim> </AdditionalHeaders> <TimeAllowance>30s</TimeAllowance> <Source>input_var</Source> </VerifyJWT>
En el ejemplo anterior, se usa el elemento <Algorithms>
, por lo que se verifica un JWT encriptado. El elemento <PrivateKey>
especifica la clave que se usará para desencriptar el JWT. También hay otros elementos clave. El que uses depende del algoritmo que especifica el valor de <Algorithms>
, como se describe en la sección siguiente.
Configura los elementos clave para verificar un JWT encriptado
En los siguientes elementos, se especifica la clave que se usa para verificar un JWT encriptado:
El elemento que uses depende del algoritmo de encriptación de clave elegido, como se muestra en la siguiente tabla:
Algoritmo | Elementos clave |
---|---|
RSA-OAEP-256 | <PrivateKey> <Value ref="private.rsa_privatekey"/> </PrivateKey> Nota: La variable que especifiques debe resolverse en una clave privada RSA en formato con codificación PEM. |
|
<PrivateKey> <Value ref="private.ec_privatekey"/> </PrivateKey> Nota: La variable que especifiques debe resolverse en una clave privada de curva elíptica en forma de codificación PEM. |
|
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.flow-variable-name-here"/> </SecretKey> |
|
<PasswordKey> <Value ref="private.password-key"/> <SaltLength> <PBKDF2Iterations> </PasswordKey> |
dir | <DirectKey> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey> |
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 JWT.
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
<VerifyJWT name="JWT" 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 |
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 |
verdadero | Opcional |
async | Este atributo dejó de estar disponible. | falso | Obsoleto |
<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 criptográfico que se usa para verificar el token. Usa el elemento <Algorithm>
para verificar un JWT firmado.
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 |
<Algorithms>
<Algorithms> <Key>key-algorithm</Key> <Content>content-algorithm</Content> </Algorithm>
Usa el elemento <Algorithms>
para verificar un JWT encriptado. Este elemento especifica el algoritmo criptográfico para la encriptación de claves que se debe haber usado cuando se creó el JWT encriptado. De manera opcional, también especifica el algoritmo para la encriptación de contenido.
Valor predeterminado | N/A |
Presencia | Obligatorio cuando se verifica un JWT encriptado |
Tipo | Complejo |
Elementos secundarios de <Algorithms>
En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <Algorithms>
:
Elemento secundario | ¿Es obligatorio? | Descripción |
---|---|---|
<Key> |
Obligatorio | Especifica el algoritmo de encriptación de la clave. |
<Content> |
Opcional | Especifica el algoritmo de encriptación para el contenido. |
La verificación fallará en los siguientes casos:
- El algoritmo declarado en la propiedad
alg
en el encabezado del JWT encriptado es diferente del algoritmo de encriptación de claves especificado aquí en el elemento<Key>
. -
La política especifica un elemento
<Content>
y el algoritmo confirmado en la propiedadenc
del encabezado del JWT encriptado es diferente del especificado en el elemento<Content>
.
Por ejemplo, para verificar un JWT encriptado y verificar que el algoritmo de clave sea RSA-OAEP-256
y que el algoritmo de contenido sea A128GCM
, haz lo siguiente:
<Algorithms> <Key>RSA-OAEP-256</Key> <Content>A128GCM</Content> </Algorithms>
Por el contrario, para verificar un JWT encriptado y verificar que el algoritmo de clave sea RSA-OAEP-256
y no aplicar una restricción en el algoritmo de contenido, haz lo siguiente:
<Algorithms> <Key>RSA-OAEP-256</Key> </Algorithms>
Algoritmos de encriptación de claves
En la siguiente tabla, se enumeran los algoritmos disponibles para la encriptación de claves, así como el tipo de clave que debes especificar para verificar un JWT con ese algoritmo de encriptación de claves.
Valor de <Key> (algoritmo de encriptación de claves) |
Elemento de clave necesario para la verificación |
---|---|
dir | <DirectKey> |
RSA-OAEP-256 | <PrivateKey> |
|
<SecretKey> |
|
<PasswordKey> |
|
<PrivateKey> |
Consulta Verifica un JWT encriptado para ver un ejemplo en el que el algoritmo de encriptación de claves es RSA-OAEP-256
, por lo que debes usar el elemento <PrivateKey>
.
Algoritmos de encriptación de contenido
La política VerifyJWT no requiere que especifiques un algoritmo para la encriptación de contenido. Si deseas especificar el algoritmo que se usa para la encriptación de contenido, hazlo con el secundario <Content> del elemento <Algorithms>.
Sin importar el algoritmo de encriptación de claves, los siguientes algoritmos, todos simétricos y basados en AES, son compatibles con la encriptación de contenido:
- A128CBC-HS256
- A192CBC-HS384
- A256CBC-HS512
- A128GCM
- A192GCM
- A256GCM
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable-name-here'/>
La política verifica que la reclamación de público en el JWT coincida con el valor especificado en la configuración. Si no hay coincidencias, la política generará un error. Esta reclamación identifica a los destinatarios para los que está destinado el JWT. Esta es una de las reclamaciones registradas que se mencionan en RFC7519.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String |
Valores válidos | Una variable o string de flujo que identifica al público. |
<AdditionalClaims/Claim>
<AdditionalClaims> <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'/> </AdditionalClaims> or: <AdditionalClaims ref='claim_payload'/>
Valida que la carga útil de JWT contenga las reclamaciones adicionales especificadas y que los valores de la reclamación confirmada coincidan.
Un reclamación adicional usa un nombre que no es uno de los nombres de reclamación JWT registrados y estándar. 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, número, booleano o mapa |
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
Cuando incluyes el elemento <Claim>
, los nombres de la reclamación se configuran de forma estática cuando configuras la política. Como alternativa, puedes pasar un objeto JSON para especificar los nombres de la reclamación.
Debido a que el objeto JSON se pasa como una variable, los nombres de la reclamación se determinan durante el entorno de ejecución.
Por ejemplo:
<AdditionalClaims ref='json_claims'/>
En el que la variable json_claims
contiene un objeto JSON en el siguiente formato:
{ "sub" : "person@example.com", "iss" : "urn://secure-issuer@example.com", "non-registered-claim" : { "This-is-a-thing" : 817, "https://example.com/foobar" : { "p": 42, "q": false } } }
<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 JWT contenga los pares de valor o nombres de reclamos adicionales especificados y que coincidan los valores de la reclamación confirmada.
Una reclamación adicional usa un nombre que no es uno de los nombres de reclamación JWT registrados y estándar. 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
<CustomClaims>
Nota: Por el momento, se inserta un elemento CustomClaims cuando agregas una política GenerateJWT nueva a través de la IU. Este elemento no es funcional y se ignora. El elemento correcto que debe usarse es <AdditionalClaims>. La IU se actualizará para insertar los elementos correctos más adelante.
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
Verifica que el JWT tenga la reclamación jti específica. Cuando el valor de texto y el atributo ref están vacíos, la política generará un jti que contiene un UUID aleatorio. La reclamación de ID de JWT (jti) es un identificador único para el JWT. Para obtener más información sobre jti, consulta RFC7519.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String o referencia. |
Valores válidos | Una string o el nombre de una variable de flujo que contiene el ID. |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Configúralo como falso si deseas que la política genere un error cuando algún encabezado que figura en el encabezado crit del JWT no aparezca en el elemento <KnownHeaders>
.
Se establece como verdadero para que la política VerifyJWT ignore el encabezado crit.
Un motivo para establecer este elemento como verdadero es si estás en un entorno de pruebas y aún no estás listo para controlar una falla en un encabezado faltante.
Valor predeterminado | falso |
Presencia | Opcional |
Tipo | Booleano |
Valores válidos | True o False |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
Configúralo como falso (predeterminado) si deseas que la política genere un error cuando un JWT contenga una reclamación iat
(emitida en) que especifique una hora en el futuro.
Se establece como verdadero para que la política ignore iat
durante la verificación.
Valor predeterminado | 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 |
<Issuer>
<VerifyJWT name='VJWT-29'> ... <!-- verify that the iss claim matches a hard-coded value --> <Issuer>issuer-string-here</Issuer> or: <!-- verify that the iss claim matches the value contained in a variable --> <Issuer ref='variable-containing-issuer'/> or: <!-- verify via a variable; fallback to a hard-coded value if the variable is empty --> <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>
La política verifica que la entidad emisora en el JWT (el reclamo iss
) coincida con la cadena especificada en el elemento de configuración. El reclamo iss
es uno de los reclamos registrados que se mencionan en IETF RFC 7519.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String o referencia |
Valores válidos | Cualquiera |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref='variable_containing_headers'/>
La política GenerateJWT usa el elemento <CriticalHeaders>
para propagar el encabezado crit en un JWT. Por ejemplo:
{ "typ": "...", "alg" : "...", "crit" : [ "a", "b", "c" ], }
La política GenerateJWT examina el encabezado crit en el JWT, si existe, y por cada encabezado 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>
genera que la política VerifyJWT falle.
De forma opcional, puedes configurar la política VerifyJWT para ignorar el encabezado crit si estableces el elemento <IgnoreCriticalHeaders>
como true
.
Valor predeterminado | 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. |
<MaxLifespan>
<VerifyJWT name='VJWT-62'> ... <!-- hard-coded lifespan of 5 minutes --> <MaxLifespan>5m</MaxLifespan> or: <!-- refer to a variable --> <MaxLifespan ref='variable-here'/> or: <!-- attribute telling the policy to use iat rather than nbf --> <MaxLifespan useIssueTime='true'>1h</MaxLifespan> or: <!-- useIssueTime and ref, and hard-coded fallback value. --> <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan> ...
Configura la política VerifyJWT para que verifique que la vida útil de un token no exceda un umbral especificado. Puedes especificar el umbral a través de un número seguido de un carácter, que indica la cantidad de segundos, minutos, horas, días o semanas. Los siguientes caracteres son válidos:
s
- segundosm
- minutosh
- horasd
- díasw
- semanas
Por ejemplo, puedes especificar uno de los siguientes valores: 120 s, 10 m, 1 h, 7 d o 3 se.
La política calcula la vida útil real del token a través de la resta del valor no anterior (nbf)
del valor de vencimiento (exp)
. Si faltan exp
o nbf
, la política muestra una falla. Si la vida útil del token supera el período especificado, la política muestra una falla.
Puedes configurar el atributo opcional useIssueTime
como true
para usar el valor iat
en lugar del valor nbf
cuando se calcula la vida útil del token.
El uso del elemento MaxLifespan
es opcional. Si usas este elemento, puedes usarlo solo una vez.
<PrivateKey>
Usa este elemento para especificar la clave privada que se puede usar para verificar un JWT encriptado con un algoritmo asimétrico. A continuación, se incluye una descripción de los posibles elementos secundarios.
<Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
Un elemento secundario del elemento <PrivateKey>
. Especifica la contraseña que debe usar la política para desencriptar la clave privada, si es necesario, cuando verifiques un JWT encriptado.
Usa el atributo ref
para pasar la clave en una variable de flujo.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String |
Valores válidos |
Una referencia de variable de flujo.
Nota: Debes especificar una variable de flujo. Apigee rechazará la configuración de la política como no válida en la que la contraseña se especifica en texto simple. La variable de flujo debe tener el prefijo “privado”. Por ejemplo, |
<Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
Un elemento secundario del elemento <PrivateKey>
. Especifica una clave privada con codificación PEM que la política usará para verificar un JWT encriptado. Usa el atributo ref
para pasar la clave en una variable de flujo.
Valor predeterminado | N/A |
Presencia | Obligatorio para verificar un JWT que se encriptó a través de un algoritmo de encriptación de claves asimétrico. |
Tipo | String |
Valores válidos |
Una variable de flujo que contiene una string que representa un valor de clave privada RSA con codificación PEM.
Nota: La variable de flujo debe tener el prefijo “privado”. Por ejemplo: |
<PublicKey>
Especifica la fuente de la clave pública que se usa para verificar un JWT firmado con un algoritmo asimétrico. Los algoritmos de asistencia incluyen RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512. A continuación, se incluye una descripción de los posibles elementos secundarios.
<Certificate>
<PublicKey> <Certificate ref="signed_public.cert"/> </PublicKey> -or- <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- cert data -----END CERTIFICATE----- </Certificate> </PublicKey>
Un elemento secundario del elemento <PublicKey>
. Especifica el certificado firmado
que se usa como fuente de la clave pública. Usa el atributo ref
para pasar el certificado firmado en una variable de flujo o especifica el certificado codificado de forma directa con PEM.
Valor predeterminado | N/A |
Presencia | Opcional. Para verificar un JWT firmado con un algoritmo asimétrico, debes usar el elemento <Certificate> , <JWKS> o <Value> para proporcionar la clave pública. |
Tipo | String |
Valores válidos | Una cadena o variable de flujo. |
<JWKS>
<PublicKey> <JWKS … > … </JWKS> </PublicKey>
Un elemento secundario del elemento <PublicKey>
. Especifica un JWKS como fuente de claves públicas. Esta será una lista de claves con el formato descrito en IETF RFC 7517 - JSON Web Key (JWK).
Si el JWT entrante tiene un ID de clave que está presente en el JWKS, la política usará la clave pública correcta para verificar la firma de JWT. Para obtener detalles sobre esta característica, consulta Usa un conjunto de claves web JSON (JWKS) para verificar un JWT.
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 | Opcional. Para verificar un JWT firmado con un algoritmo asimétrico, debes usar el elemento <Certificate> , <JWKS> o <Value> para proporcionar la clave pública. |
Tipo | String |
Valores válidos |
Puedes especificar el JWKS de cuatro maneras:
|
<Value>
<PublicKey> <Value ref="public.publickeyorcert"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW ...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
Es un elemento secundario del elemento <PublicKey>
. Especifica la clave pública que se usará para verificar la firma en un JWT firmado. Usa el atributo ref
para pasar la clave en una variable de flujo o especifica la clave codificada de forma directa de PEM.
Valor predeterminado | N/A |
Presencia | Opcional. Para verificar un JWT firmado con un algoritmo asimétrico, debes usar el elemento <Certificate> , <JWKS> o <Value> para proporcionar la clave pública. |
Tipo | String |
Valores válidos | Una cadena o variable de flujo. |
<RequiredClaims>
<VerifyJWT name='VJWT-1'> ... <!-- Directly specify the names of the claims to require --> <RequiredClaims>sub,iss,exp</RequiredClaims> -or- <!-- Specify the claim names indirectly, via a context variable --> <RequiredClaims ref='claims_to_require'/> ... </VerifyJWT>
El elemento <RequiredClaims>
es opcional. Especifica una lista de nombres de reclamos separados por comas que deben estar presentes en la carga útil de JWT cuando se verifica un JWT. El elemento garantiza que el JWT presentado contenga las afirmaciones requeridas, pero no valida el contenido de las reclamaciones. Si no está presente ninguna de las reclamaciones enumeradas, la política VerifyJWT arrojará una falla durante el tiempo de ejecución.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String |
Valores válidos | Una lista separada por comas de los nombres de las reclamaciones. |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Value ref="private.your-variable-name"/> </SecretKey>
El elemento SecretKey es opcional. Especifica la clave secreta que se usará cuando se verifique un JWT firmado que usa un algoritmo simétrico (HS*) o cuando se verifica un JWT encriptado que usa un algoritmo simétrico (AES) para la encriptación de claves.
Secundarios de <SecretKey>
En la siguiente tabla, se proporciona una descripción de los elementos secundarios y los atributos de <SecretKey>
:
Hijo | 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 <SecretKey encoding="hex" > <Value ref="private.secretkey"/> </SecretKey> En el ejemplo anterior, debido a que la codificación es |
Valor (elemento) | Obligatorio | Una clave secreta codificada. Especifica la clave secreta que se usará
para verificar la carga útil. Usa el atributo <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>jwt-variable</Source>
Si está presente, especifica la variable de flujo en la que la política espera encontrar el JWT que se verificará.
Con este elemento, puedes configurar la política para recuperar el JWT desde una variable de parámetro de consulta o formulario, o cualquier otra variable. Cuando este elemento está presente, la política no quitará ningún prefijo Bearer
que pueda estar presente. Si la variable no existe o si la política no encuentra un JWT en la variable especificada, la política devuelve un error.
De forma predeterminada, cuando no hay ningún elemento <Source>
presente, la política recupera el JWT a través de la lectura de la variable request.header.authorization
y la eliminación del prefijo Bearer
. Si pasas el JWT en el encabezado de autorización como un token del portador (con el prefijo Bearer
), no especifiques el elemento <Source>
en la configuración de la política. Por ejemplo, no usarías ningún elemento <Source>
en la configuración de la política si pasas el JWT en el encabezado de autorización de la siguiente manera:
curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Valor predeterminado | 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. |
<Subject>
<VerifyJWT name='VJWT-8'> ... <!-- verify that the sub claim matches a hard-coded value --> <Subject>subject-string-here</Subject> or: <!-- verify that the sub claim matches the value contained in a variable --> <Subject ref='variable-containing-subject'/> or: <!-- verify via a variable; fallback to a hard-coded value if the variable is empty --> <Subject ref='variable-containing-subject'>fallback-value-here</Subject>
La política verifica que el asunto en el JWT (la reclamación sub
) coincida con la string especificada en la configuración de la política. La reclamación sub
es una de las reclamaciones registradas que se describen en RFC7519.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String |
Valores válidos | Cualquier valor que identifique de forma única a un asunto. |
<TimeAllowance>
<VerifyJWT name='VJWT-23'> ... <!-- configure a hard-coded time allowance of 20 seconds --> <TimeAllowance>20s</TimeAllowance> or: <!-- refer to a variable containing the time allowance --> <TimeAllowance ref='variable-containing-time-allowance'/> or: <!-- refer to a variable; fallback to a hard-coded value if the variable is empty --> <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>
El “período de gracia” de los horarios, para tener en cuenta la discrepancia de reloj entre el emisor y el verificador de un JWT. Esto se aplicará tanto al vencimiento (la reclamación exp
) al intervalo anterior al horario (la reclamación nbf
). Por ejemplo, si la asignación de tiempo se configura para que sea 30s
, un JWT vencido se tratará como válido durante 30 segundos después de la declaración de vencimiento. El intervalo antes del horario se evaluará de forma similar.
Valor predeterminado | 0 segundos (sin período de gracia) |
Presencia | Opcional |
Tipo | String |
Valores válidos |
Una expresión de período o una referencia a una variable de flujo que contiene una expresión.
Los intervalos de tiempo se pueden especificar con un número entero positivo seguido de un carácter que indique
una unidad de tiempo, de la siguiente manera:
|
<Type>
<Type>type-string-here</Type>
Describe si la política verifica un JWT firmado o un JWT encriptado.
El elemento <Type>
es opcional. Puedes usarla para informar a los lectores sobre la configuración si la política genera un JWT firmado o encriptado.
- Si el elemento
<Type>
está presente:- Si el valor de
<Type>
esSigned
, la política verifica un JWT firmado y el elemento<Algorithm>
debe estar presente. - Si el valor de
<Type>
esEncrypted
, la política verifica un JWT encriptado y el elemento<Algorithms>
debe estar presente.
- Si el valor de
- Si el elemento
<Type>
está ausente:- Si el elemento
<Algorithm>
está presente, la política supone que<Type>
esSigned
. - Si el elemento
<Algorithms>
está presente, la política supone que<Type>
esEncrypted
.
- Si el elemento
- Si ni
<Algorithm>
ni<Algorithms>
están presentes, la configuración no es válida.
Valor predeterminado | N/A |
Presencia | Opcional |
Tipo | String |
Valores válidos | Signed o Encrypted |
Variables de flujo
Si se ejecuta de forma correcta, las políticas de verificación de JWT y decodificación de JWT establecen variables de contexto según este patrón:
jwt.{policy_name}.{variable_name}
Por ejemplo, si el nombre de la política es jwt-parse-token
, la política almacenará el asunto especificado en el JWT en esta variable de contexto: jwt.jwt-parse-token.decoded.claim.sub
(Para la retrocompatibilidad, también estará disponible en jwt.jwt-parse-token.claim.subject
).
Nombre de la variable | Descripción |
---|---|
claim.audience |
La reclamación de público de JWT. Este valor puede ser una string o un arreglo de strings. |
claim.expiry |
La fecha y hora de vencimiento, expresada en segundos desde el ciclo de entrenamiento. |
claim.issuedat |
La fecha en que se emitió el token, expresada en segundos desde el ciclo de entrenamiento. |
claim.issuer |
La reclamación de la entidad emisora de JWT. |
claim.notbefore |
Si el JWT incluye una reclamación nbf, esta variable contendrá el valor, expresado en milisegundos desde el ciclo de entrenamiento. |
claim.subject |
La reclamación del asunto de JWT. |
claim.name |
El valor de la reclamación con nombre (estándar o adicional) en la carga útil. Uno de estos se configurará para cada reclamación en la carga útil. |
decoded.claim.name |
El valor JSON analizable de la reclamación con nombre (estándar o adicional) en la carga útil. Se configura una variable para cada reclamación en la carga útil. Por ejemplo, puedes usar decoded.claim.iat para recuperar la hora de emisión del JWT, expresada en segundos desde el ciclo de entrenamiento. Si bien también puedes usar las variables de flujo claim.name , esta es la variable recomendada para acceder a una reclamació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. |
expiry_formatted |
La fecha y hora de vencimiento, con formato de string legible. Ejemplo: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
El algoritmo de firma que se usa en el JWT. 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 JWT. Consulta también “Usa el conjunto de claves web de JSON (JWKS)” en la descripción general de las políticas de JWT para verificar uno. Consulta el Parámetro de encabezado (ID de clave) para obtener más información. |
header.type |
Se configurará como JWT . |
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 del JWT. |
header-json |
El encabezado en formato JSON |
is_expired |
True o False |
payload-claim-names |
Un arreglo de reclamaciones compatibles con JWT. |
payload-json |
La carga útil en formato JSON.
|
seconds_remaining |
La cantidad de segundos antes de que venza el token. Si el token venció, este número será negativo. |
time_remaining_formatted |
El tiempo restante antes de que el token venza, con el formato de una string legible. Ejemplo: 00:59:59.926 |
valid |
En el caso de VerifyJWT, 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. De lo contrario, es falso.
En el caso de DecodeJWT, esta variable no está configurada. |
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.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 |
Occurs when the verification policy has multiple algorithms. |
steps.jwt.AlgorithmMismatch |
401 |
The algorithm specified in the Generate policy did not match the one expected in the
Verify policy. The algorithms specified must match. |
steps.jwt.FailedToDecode |
401 |
The policy was unable to decode the JWT. The JWT is possibly corrupted. |
steps.jwt.GenerationFailed |
401 |
The policy was unable to generate the JWT. |
steps.jwt.InsufficientKeyLength |
401 |
For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm. |
steps.jwt.InvalidClaim |
401 |
For a missing claim or claim mismatch, or a missing header or header mismatch. |
steps.jwt.InvalidConfiguration |
401 |
Both the <Algorithm> and <Algorithms> elements
are present. |
steps.jwt.InvalidCurve |
401 |
The curve specified by the key is not valid for the Elliptic Curve algorithm. |
steps.jwt.InvalidIterationCount |
401 |
The iteration count that was used in the encrypted JWT is not equal to the iteration
count specified in the VerifyJWT policy configuration. This applies only to JWT that
use <PasswordKey> . |
steps.jwt.InvalidJsonFormat |
401 |
Invalid JSON found in the header or payload. |
steps.jwt.InvalidKeyConfiguration |
401 |
JWKS in the <PublicKey> element is invalid. The reason
could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test
connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint
as a target. |
steps.jwt.InvalidSaltLength |
401 |
The salt length that was used in the encrypted JWT is not equal to the salt length
specified in the VerifyJWT policy configuration. This applies only to JWT that
use <PasswordKey> . |
steps.jwt.InvalidPasswordKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidPrivateKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidPublicKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidSecretKey |
401 |
The specified key specified did not meet the requirements. |
steps.jwt.InvalidToken |
401 |
This error occurs when the JWT signature verification fails. |
steps.jwt.JwtAudienceMismatch |
401 |
The audience claim failed on token verification. |
steps.jwt.JwtIssuerMismatch |
401 |
The issuer claim failed on token verification. |
steps.jwt.JwtSubjectMismatch |
401 |
The subject claim failed on token verification. |
steps.jwt.KeyIdMissing |
401 |
The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not
include a kid property in the header. |
steps.jwt.KeyParsingFailed |
401 |
The public key could not be parsed from the given key information. |
steps.jwt.NoAlgorithmFoundInHeader |
401 |
Occurs when the JWT contains no algorithm header. |
steps.jwt.NoMatchingPublicKey |
401 |
The Verify policy uses a JWKS as a source for public keys, but the kid
in the signed JWT is not listed in the JWKS. |
steps.jwt.SigningFailed |
401 |
In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms |
steps.jwt.TokenExpired |
401 |
The policy attempts to verify an expired token. |
steps.jwt.TokenNotYetValid |
401 |
The token is not yet valid. |
steps.jwt.UnhandledCriticalHeader |
401 |
A header found by the Verify JWT policy in the crit header is not
listed in KnownHeaders . |
steps.jwt.UnknownException |
401 |
An unknown exception occurred. |
steps.jwt.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 | Cause | Fix |
---|---|---|
InvalidNameForAdditionalClaim |
The deployment will fail if the claim used in the child element <Claim>
of the <AdditionalClaims> element is one of the following registered names:
kid , iss , sub , aud , iat ,
exp , nbf , or jti .
|
build |
InvalidTypeForAdditionalClaim |
If the claim used in the child element <Claim>
of the <AdditionalClaims> element is not of type string , number ,
boolean , or map , the deployment will fail.
|
build |
MissingNameForAdditionalClaim |
If the name of the claim is not specified in the child element <Claim>
of the <AdditionalClaims> element, the deployment will fail.
|
build |
InvalidNameForAdditionalHeader |
This error ccurs when the name of the claim used in the child element <Claim>
of the <AdditionalClaims> element is either alg or typ .
|
build |
InvalidTypeForAdditionalHeader |
If the type of claim used in the child element <Claim>
of the <AdditionalClaims> element is not of type string , number ,
boolean , or map , the deployment will fail.
|
build |
InvalidValueOfArrayAttribute |
This error occurs when the value of the array attribute in the child element <Claim>
of the <AdditionalClaims> element is not set to true or false .
|
build |
InvalidValueForElement |
If the value specified in the <Algorithm> element is not a supported value,
the deployment will fail.
|
build |
MissingConfigurationElement |
This error will occur if the <PrivateKey> element is not used with
RSA family algorithms or the <SecretKey> element is not used with HS Family
algorithms.
|
build |
InvalidKeyConfiguration |
If the child element <Value> is not defined in the <PrivateKey>
or <SecretKey> elements, the deployment will fail.
|
build |
EmptyElementForKeyConfiguration |
If the ref attribute of the child element <Value> of the <PrivateKey>
or <SecretKey> elements is empty or unspecified, the deployment will fail.
|
build |
InvalidConfigurationForVerify |
This error occurs if the <Id> element is defined within the
<SecretKey> element.
|
build |
InvalidEmptyElement |
This error occurs if the <Source> element of the Verify JWT policy
is empty. If present, it must be defined with an Apigee flow variable name.
|
build |
InvalidPublicKeyValue |
If the value used in the child element <JWKS> of the <PublicKey> element
does not use a valid format as specified in RFC 7517,
the deployment will fail.
|
build |
InvalidConfigurationForActionAndAlgorithm |
If the <PrivateKey> element is used with HS Family algorithms or
the <SecretKey> element is used with RSA Family algorithms, the
deployment will fail.
|
build |
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 "InvalidToken" |
JWT.failed |
All JWT policies set the same variable in the case of a failure. | JWT.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="JWT Policy Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "InvalidToken")</Condition> </Step> <Condition>JWT.failed=true</Condition> </FaultRule> </FaultRules>