Política VerifyJWT

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

Consulta la documentación de Apigee Edge.

La política VerifyJWT verifica un JWT firmado o descifra y verifica un JWT cifrado recibido de clientes u 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 y tomar decisiones de autorización o de enrutamiento. Consulta la información general sobre las políticas de JWS y JWT para obtener una introducción detallada.

Cuando se ejecuta esta política, en el caso de un JWT firmado, Apigee verifica la firma del JWT mediante la clave de verificación proporcionada. En el caso de un JWT cifrado, Apigee descifra el JWT con la clave de descifrado. En cualquier caso, Apigee verifica posteriormente que el JWT sea válido según las horas de vencimiento y de inicio, si están presentes. La política también puede verificar opcionalmente los valores de reclamaciones específicas en el JWT, como el asunto, el emisor, la audiencia o el valor de reclamaciones adicionales.

Si el JWT se verifica y es válido, todas las reclamaciones que contiene se extraen en variables de contexto para que las usen las políticas o condiciones posteriores, y se permite que la solicitud continúe. Si no se puede verificar la firma del JWT o si el JWT no es válido debido a una de las marcas de tiempo, se detendrá todo el procesamiento y se devolverá un error en la respuesta.

Si la política verifica un JWT firmado o cifrado, depende del elemento que utilices para especificar el algoritmo que verifica el JWT:

Esta política es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad de cada tipo de entorno, consulta Tipos de políticas.

Para obtener información sobre las partes de un JWT y cómo se cifran y firman, consulta el RFC7519.

Verificar un JWT firmado

En esta sección se explica cómo verificar un JWT firmado. En el caso de los JWT firmados, usa el elemento <Algorithm> para especificar el algoritmo de firma de la clave.

Ejemplos de un JWT firmado

En los siguientes ejemplos se muestra cómo verificar un JWT firmado.

Algoritmo HS256

Esta política de ejemplo verifica un JWT que se ha firmado con el algoritmo de cifrado HS256, HMAC mediante una suma de comprobación SHA-256. El JWT se transmite en la solicitud proxy mediante un parámetro de formulario llamado jwt. La clave se incluye en una variable llamada private.secretkey. En el vídeo de arriba puedes ver un ejemplo completo, incluido cómo enviar una solicitud para aplicar la política.

La configuración de la política incluye la información que necesita Apigee para decodificar y evaluar el JWT, como dónde encontrar el JWT (en una variable de flujo especificada en el elemento Source), el algoritmo de firma necesario, dónde encontrar la clave secreta (almacenada en una variable de flujo de Apigee, que podría haberse obtenido del KVM de Apigee, por ejemplo) y un conjunto de reclamaciones obligatorias 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 salida en variables de contexto para que las políticas o condiciones posteriores del proxy de API puedan examinar esos valores. Consulta Variables de flujo para ver una lista de las variables definidas por esta política.

Algoritmo RS256

Esta política de ejemplo verifica un JWT que se ha firmado con el algoritmo RS256. Para verificarla, debes proporcionar la clave pública. El JWT se transmite en la solicitud proxy mediante un parámetro de formulario llamado jwt. La clave pública se incluye en una variable llamada public.publickey. En el vídeo de arriba puedes ver un ejemplo completo, incluido cómo enviar una solicitud para aplicar la política.

Consulta la referencia de elementos para obtener información sobre los requisitos y las opciones de cada elemento de esta política de ejemplo.

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

En 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á válida si la firma se puede verificar 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álido, aunque se pueda verificar la firma, porque la reclamación "sub" incluida en el JWT no coincide con el valor obligatorio del elemento "Subject" tal como se especifica en la configuración de la política.

La política escribe su salida en variables de contexto para que las políticas o condiciones posteriores del proxy de API puedan examinar esos valores. Consulta Variables de flujo para ver una lista de las variables definidas por esta política.

En los ejemplos anteriores se usa el elemento <Algorithm>, por lo que se verifica un JWT firmado. El elemento <PrivateKey> especifica la clave que se usa para firmar el JWT. También hay otros elementos clave. El que uses dependerá del algoritmo especificado por el valor de <Algorithm>, tal como se describe en la siguiente sección.

Definir los elementos clave para verificar un JWT firmado

Los siguientes elementos especifican la clave que se usa para verificar un JWT firmado:

El elemento que uses dependerá del algoritmo elegido, tal 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>

También puedes hacerlo de esta otra forma, si lo prefieres:

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

También puedes hacerlo de esta otra forma, si lo prefieres:

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

Verificar un JWT cifrado

En esta sección se explica cómo verificar un JWT cifrado. En el caso de los JWT cifrados, usa el elemento <Algorithms> para especificar los algoritmos de firma de la clave y el contenido.

Ejemplo de un JWT cifrado

En el siguiente ejemplo se muestra cómo verificar un JWT cifrado (con <Type> definido como Encrypted), en el que:

  • La clave se cifra con el algoritmo RSA-OAEP-256.
  • El contenido se cifra 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 cifrado. El elemento <PrivateKey> especifica la clave que se usará para descifrar el JWT. También hay otros elementos clave. El que uses dependerá del algoritmo especificado por el valor de <Algorithms>, tal como se describe en la siguiente sección.

Definir los elementos clave para verificar un JWT cifrado

Los siguientes elementos especifican la clave que se usa para verificar un JWT cifrado:

El elemento que uses dependerá del algoritmo de cifrado de claves elegido, tal 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 codificado en PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Nota: La variable que especifiques debe resolverse en una clave privada de curva elíptica en formato codificado con PEM.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<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 Acerca de los algoritmos de cifrado de firma.

Referencia de elemento

En la referencia de la política se describen los elementos y atributos de la política Verify JWT.

Nota: La configuración variará ligeramente en función del algoritmo de cifrado que utilices. Consulta los ejemplos para ver configuraciones de casos prácticos específicos.

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 principales de la política.

Atributo Descripción Predeterminado Presencia
name El nombre interno de la política. Solo puedes usar los siguientes caracteres en el nombre: A-Z0-9._\-$ %. Sin embargo, la interfaz de usuario de Apigee aplica restricciones adicionales, como la eliminación automática de caracteres que no son alfanuméricos.

También puedes usar el elemento <displayname></displayname> para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado en la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política.

 falso Opcional
habilitada Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará, aunque siga adjunta a un flujo.

 true Opcional
asíncrono Este atributo está obsoleto. falso Obsoleto

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

Predeterminado Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

<Algorithm>

<Algorithm>HS256</Algorithm>

Especifica el algoritmo criptográfico que se usa para verificar el token. Usa el elemento <Algorithm> para verificar un JWT firmado.

Los algoritmos RS*/PS*/ES* utilizan un par de claves pública y secreta, mientras que los algoritmos HS* utilizan un secreto compartido. Consulta también Acerca de los algoritmos de cifrado de firma.

Puede especificar varios valores separados por comas. Por ejemplo, "HS256, HS512" o "RS256, PS256". Sin embargo, no puedes combinar algoritmos HS* con otros ni algoritmos ES* con otros, ya que requieren un tipo de clave específico. Puedes combinar algoritmos RS* y PS*.

Predeterminado N/A
Presencia Obligatorio
Tipo Cadena de valores separados por comas
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 y PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Usa el elemento <Algorithms> para verificar un JWT cifrado. Este elemento especifica el algoritmo criptográfico para el cifrado de claves que se debe haber usado cuando se creó el JWT cifrado. También especifica de forma opcional el algoritmo de cifrado del contenido.

Predeterminado N/A
Presencia Obligatorio al verificar un JWT cifrado.
Tipo Complejo

Elementos secundarios de <Algorithms>

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <Algorithms>:

Elemento secundario ¿Es obligatorio? Descripción
<Key> Obligatorio Especifica el algoritmo de cifrado de la clave.
<Content> Opcional Especifica el algoritmo de cifrado del contenido.

La verificación fallará si:

  • El algoritmo indicado en la propiedad alg de la cabecera del JWT cifrado es distinto del algoritmo de cifrado de clave especificado en el elemento <Key>.
  • La política especifica un elemento <Content> y el algoritmo afirmado en la propiedad enc del encabezado del JWT cifrado es diferente del especificado en el elemento <Content>.

Por ejemplo, para verificar un JWT cifrado y comprobar que el algoritmo de la clave es RSA-OAEP-256 y que el algoritmo del contenido es A128GCM, haz lo siguiente:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

Por el contrario, para verificar un JWT cifrado y comprobar que el algoritmo de la clave es RSA-OAEP-256, pero sin aplicar ninguna restricción al algoritmo de contenido, haz lo siguiente:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

Algoritmos de cifrado de claves

En la siguiente tabla se indican los algoritmos disponibles para el cifrado de claves, así como el tipo de clave que debes especificar para verificar un JWT con ese algoritmo de cifrado de claves.

Valor de <Key> (algoritmo de cifrado de claves) Elemento clave necesario para la verificación
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

Consulta Verificar un JWT cifrado para ver un ejemplo en el que el algoritmo de cifrado de claves es RSA-OAEP-256, por lo que se usa el elemento <PrivateKey>.

Algoritmos de cifrado de contenido

La política VerifyJWT no requiere que especifiques un algoritmo para el cifrado de contenido. Si quieres especificar el algoritmo utilizado para cifrar el contenido, hazlo con el elemento secundario<Content> del elemento <Algorithms>.

Independientemente del algoritmo de cifrado de claves, se admiten los siguientes algoritmos de cifrado de contenido, que son simétricos y se basan en AES:

  • 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 audiencia del JWT coincida con el valor especificado en la configuración. Si no hay ninguna coincidencia, la política genera un error. Esta reclamación identifica a los destinatarios a los que va dirigido el JWT. Se trata de una de las reclamaciones registradas que se mencionan en RFC7519.

Predeterminado N/A
Presencia Opcional
Tipo Cadena
Valores válidos Una variable de flujo o una cadena que identifica la audiencia.

<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 del JWT contiene las reclamaciones adicionales especificadas y que los valores de las reclamaciones confirmadas coinciden.

Una reclamación adicional usa un nombre que no es uno de los nombres de reclamación JWT estándar registrados. El valor de una reclamación adicional puede ser una cadena, un número, un valor booleano, un mapa o una matriz. Un mapa es simplemente un conjunto de pares nombre/valor. El valor de una reclamación de cualquiera de estos tipos se puede especificar explícitamente en la configuración de la política o indirectamente mediante una referencia a una variable de flujo.

Predeterminado N/A
Presencia Opcional
Tipo Cadena, número, valor booleano o mapa
Array Asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false
Valores válidos Cualquier valor que quieras usar para una reclamación adicional.

El elemento <Claim> acepta estos atributos:

  • name: (obligatorio) nombre de la reclamación.
  • ref: (opcional) Nombre de una variable de flujo. Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican tanto un atributo ref como un valor de reclamación explícito, el valor explícito será el predeterminado y se usará si la variable de flujo a la que se hace referencia no se resuelve.
  • type: (opcional) uno de los siguientes valores: string (valor predeterminado), number, boolean o map.
  • array: (opcional) asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false.

Si incluye el elemento <Claim>, los nombres de las reclamaciones se definen de forma estática cuando configura la política. También puedes enviar un objeto JSON para especificar los nombres de las reclamaciones. Como el objeto JSON se transfiere como una variable, los nombres de las reclamaciones se determinan en el tiempo de ejecución.

Por ejemplo:

<AdditionalClaims ref='json_claims'/>

La variable json_claims contiene un objeto JSON con 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 nombre/valor de la(s) reclamación(es) adicional(es) especificada(s) y que los valores de la reclamación confirmada coincidan.

Una reclamación adicional usa un nombre que no es uno de los nombres de reclamación de JWT estándar registrados. El valor de una reclamación adicional puede ser una cadena, un número, un valor booleano, un mapa o una matriz. Un mapa es simplemente un conjunto de pares nombre/valor. El valor de una reclamación de cualquiera de estos tipos se puede especificar explícitamente en la configuración de la política o indirectamente mediante una referencia a una variable de flujo.

Predeterminado N/A
Presencia Opcional
Tipo

Cadena (valor predeterminado), número, valor booleano o mapa.

Si no se especifica ningún tipo, se asigna el tipo String de forma predeterminada.
Array Asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false
Valores válidos Cualquier valor que quieras usar para una reclamación adicional.

El elemento <Claim> acepta estos atributos:

  • name: (obligatorio) nombre de la reclamación.
  • ref: (opcional) Nombre de una variable de flujo. Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican tanto un atributo ref como un valor de reclamación explícito, el valor explícito será el predeterminado y se usará si la variable de flujo a la que se hace referencia no se resuelve.
  • type: (opcional) uno de los siguientes valores: string (valor predeterminado), number, boolean o map.
  • array: (opcional) asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false.

<CustomClaims>

Nota: Actualmente, se inserta un elemento CustomClaims cuando añade una nueva política GenerateJWT a través de la interfaz de usuario. Este elemento no funciona y se ignora. El elemento correcto que debe usar es <AdditionalClaims>. La interfaz de usuario 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. Si el valor de texto y el atributo ref están vacíos, la política generará un jti que contenga un UUID aleatorio. La reclamación de ID de JWT (jti) es un identificador único del JWT. Para obtener más información sobre jti, consulta RFC7519.

Predeterminado N/A
Presencia Opcional
Tipo Cadena o referencia.
Valores válidos Una cadena o el nombre de una variable de flujo que contenga el ID.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Asigna el valor "false" si quieres que la política genere un error cuando no se incluya en el elemento <KnownHeaders> ningún encabezado de la lista del encabezado crit del JWT. Asigna el valor true para que la política VerifyJWT ignore el encabezado crit.

Uno de los motivos para asignar el valor true a este elemento es si te encuentras en un entorno de pruebas y aún no estás preparado para gestionar un error en un encabezado que falta.

Predeterminado falso
Presencia Opcional
Tipo Booleano
Valores válidos verdadero o falso

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Asigna el valor false (predeterminado) si quieres que la política genere un error cuando un JWT contenga una reclamación iat (Emitido a las) que especifique una hora futura. Asigna el valor true para que la política ignore iat durante la verificación.

Predeterminado falso
Presencia Opcional
Tipo Booleano
Valores válidos verdadero o falso

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Asigna el valor false si quieres que la política genere un error cuando no se pueda resolver ninguna variable de referencia especificada en la política. Se define como true para tratar cualquier variable que no se pueda resolver como una cadena vacía (nula).

Predeterminado falso
Presencia Opcional
Tipo Booleano
Valores válidos verdadero o falso

<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 el emisor del JWT (la reclamación iss) coincida con la cadena especificada en el elemento de configuración. La reclamación iss es una de las reclamaciones registradas que se mencionan en IETF RFC 7519.

Predeterminado N/A
Presencia Opcional
Tipo Cadena 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 rellenar el encabezado crit de un JWT. Por ejemplo:

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

La política VerifyJWT examina la cabecera crit del JWT, si existe, y, por cada cabecera que se incluya, comprueba que el elemento <KnownHeaders> también la incluya. El elemento <KnownHeaders> puede contener un superconjunto de los elementos que se indican en crit. Solo es necesario que todas las cabeceras que se indican en crit se incluyan en el elemento <KnownHeaders>. Si la política encuentra en crit un encabezado que no se incluye en <KnownHeaders>, la política VerifyJWT fallará.

También puedes configurar la política VerifyJWT para que ignore el encabezado crit asignando el valor true al elemento <IgnoreCriticalHeaders>.

Predeterminado N/A
Presencia Opcional
Tipo Matriz de cadenas separadas por comas
Valores válidos Una matriz o el nombre de una variable que contenga la matriz.

<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 comprobar que la duración de un token no supere un umbral especificado. Puedes especificar el umbral con un número seguido de un carácter que indique el número de segundos, minutos, horas, días o semanas. Los caracteres válidos son:

  • s - segundos
  • m minutos
  • h horas
  • d días
  • w semanas

Por ejemplo, puedes especificar uno de los siguientes valores: 120s, 10m, 1h, 7d o 3w.

La política calcula la duración real del token restando el valor de no anterior a (nbf) del valor de vencimiento (exp). Si falta exp o nbf, la política genera un error. Si el tiempo de vida del token supera el periodo especificado, la política genera un error.

Puede asignar el valor true al atributo opcional useIssueTime para usar el valor iat en lugar del valor nbf al calcular el tiempo de vida del token.

El uso del elemento MaxLifespan es opcional. Si usas este elemento, solo puedes hacerlo una vez.

<PrivateKey>

Usa este elemento para especificar la clave privada que se puede usar para verificar un JWT cifrado 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>

Elemento secundario del elemento <PrivateKey>. Especifica la contraseña que debe usar la política para descifrar la clave privada, si es necesario, al verificar un JWT cifrado. Use el atributo ref para transferir la contraseña en una variable de flujo.

Predeterminado N/A
Presencia Opcional
Tipo Cadena
Valores válidos Referencia a una variable de flujo.

Nota: Debes especificar una variable de flujo. Apigee rechazará como no válida una configuración de política en la que la contraseña se especifique en texto sin formato. La variable de flujo debe tener el prefijo "private". Por ejemplo, private.mypassword

<Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Elemento secundario del elemento <PrivateKey>. Especifica una clave privada codificada en PEM que la política usará para verificar un JWT cifrado. Usa el atributo ref para transferir la clave en una variable de flujo.

Predeterminado N/A
Presencia Obligatorio para verificar un JWT que se ha cifrado con un algoritmo de cifrado de clave asimétrica.
Tipo Cadena
Valores válidos Variable de flujo que contiene una cadena que representa un valor de clave privada RSA codificada en PEM.

Nota: La variable de flujo debe tener el prefijo "private". Por ejemplo: private.mykey

<PublicKey>

Especifica la fuente de la clave pública que se usa para verificar un JWT firmado con un algoritmo asimétrico. Los algoritmos admitidos son RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 y 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-----
certificate data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

Elemento secundario del elemento <PublicKey>. Especifica el certificado firmado que se usa como origen de la clave pública. Use el atributo ref para transferir el certificado firmado en una variable de flujo o especifique el certificado codificado en PEM directamente. Asegúrate de alinear los datos del certificado de la izquierda tal como se muestra en el ejemplo de referencia.

Predeterminado N/A
Presencia Opcional. Para verificar un JWT firmado con un algoritmo asimétrico, debes usar el elemento <Certificate>, el <JWKS> o el <Value> para proporcionar la clave pública.
Tipo Cadena
Valores válidos Una variable de flujo o una cadena.

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

Elemento secundario del elemento <PublicKey>. Especifica un JWKS como fuente de claves públicas. Se trata de una lista de claves con el formato descrito en IETF RFC 7517 - Clave web de JSON (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 del JWT. Para obtener más información sobre esta función, consulta Usar un conjunto de claves web JSON (JWKS) para verificar un JWT.

Si obtiene el valor de una URL pública, Apigee almacena en caché el JWKS durante un periodo de 300 segundos. Cuando caduca la caché, Apigee vuelve a obtener el JWKS.

Predeterminado N/A
Presencia Opcional. Para verificar un JWT firmado con un algoritmo asimétrico, debes usar el elemento <Certificate>, el <JWKS> o el <Value> para proporcionar la clave pública.
Tipo Cadena
Valores válidos

Puede especificar el JWKS de cuatro formas:

  • Literalmente, como valor de texto:

      <PublicKey>
    <JWKS>{
      "keys": [
        {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."},
        {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."}
      ]
    }
    </JWKS>
  </PublicKey>

  • Indirectamente, con el atributo ref, especificando una variable de flujo:

      <PublicKey>
    <JWKS ref="variable-containing-jwks-content"/>
  </PublicKey>

    La variable a la que se hace referencia debe contener una cadena que represente un JWKS.

  • Indirectamente a través de un URI estático, con el atributo uri:

      <PublicKey>
    <JWKS uri="uri-that-returns-a-jwks"/>
  </PublicKey>

  • Indirectamente a través de un URI determinado de forma dinámica, con el atributo uriRef:

      <PublicKey>
    <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/>
  </PublicKey>

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

Elemento secundario del elemento <PublicKey>. Especifica la clave pública que se va a usar para verificar la firma de un JWT firmado. Use el atributo ref para transferir la clave en una variable de flujo o especifique la clave codificada en PEM directamente. Asegúrate de alinear la clave pública de la izquierda, tal como se muestra en el ejemplo de referencia.

Predeterminado N/A
Presencia Opcional. Para verificar un JWT firmado con un algoritmo asimétrico, debes usar el elemento <Certificate>, el <JWKS> o el <Value> para proporcionar la clave pública.
Tipo Cadena
Valores válidos Una variable de flujo o una cadena.

<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 separada por comas de nombres de las reclamaciones que deben estar presentes en la carga útil del JWT al verificar un JWT. El elemento asegura que el JWT presentado contiene las reclamaciones necesarias, pero no valida el contenido de las reclamaciones. Si falta alguna de las reclamaciones enumeradas, la política VerifyJWT generará un error en el tiempo de ejecución.

Predeterminado N/A
Presencia Opcional
Tipo Cadena
Valores válidos Lista de nombres de reclamaciones separados por comas.

<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 debe usar al verificar un JWT firmado que usa un algoritmo simétrico (HS*) o al verificar un JWT cifrado que usa un algoritmo simétrico (AES) para el cifrado de claves.

Hijos de <SecretKey>

En la siguiente tabla se describen los elementos secundarios y los atributos de <SecretKey>:

Hijo/a Presencia Descripción
codificación (atributo) Opcional

Especifica cómo se codifica la clave en la variable a la que se hace referencia. De forma predeterminada, si no se incluye el atributo encoding, la codificación de la clave se trata como UTF-8. Los valores válidos del atributo son: hex, base16, base64 o base64url. Los valores de codificación hex y base16 son sinónimos.

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

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

Valor (elemento) Obligatorio

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

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

Apigee aplica una longitud mínima de clave para los algoritmos HS256, HS384 y HS512. La longitud mínima de la clave de HS256 es de 32 bytes, la de HS384 es de 48 bytes y la de HS512 es de 64 bytes. Si se usa una clave con una seguridad inferior, se produce un error de tiempo de ejecución.

<Source>

<Source>jwt-variable</Source>

Si está presente, especifica la variable de flujo en la que la política espera encontrar el JWT que se va a verificar.

Con este elemento, puede configurar la política para recuperar el JWT de una variable de parámetro de formulario o de consulta, o de cualquier otra variable. Si este elemento está presente, la política no eliminará ningún prefijo Bearer que pueda haber. 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>, la política obtiene el JWT leyendo la variable request.header.authorization y eliminando el prefijo Bearer. Si transfieres el JWT en el encabezado Authorization como un token de 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 Authorization de esta forma:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Predeterminado request.header.authorization (Consulta la nota anterior para obtener información importante sobre el valor predeterminado).
Presencia Opcional
Tipo Cadena
Valores válidos Nombre de una variable de flujo de Apigee.

<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 del JWT (la reclamación sub) coincida con la cadena especificada en la configuración de la política. La reclamación sub es una de las reclamaciones registradas que se describen en RFC7519.

Predeterminado N/A
Presencia Opcional
Tipo Cadena
Valores válidos Cualquier valor que identifique de forma única a un sujeto.

<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 "periodo de gracia" de las horas, para tener en cuenta la diferencia entre el emisor y el verificador de un JWT. Esto se aplicará tanto a la fecha de vencimiento (la reclamación exp) como al tiempo de inicio (la reclamación nbf). Por ejemplo, si el tiempo permitido es 30s, un JWT caducado se tratará como válido durante 30 segundos después de la fecha de vencimiento indicada. El tiempo anterior se evaluará de forma similar.

Predeterminado 0 segundos (sin periodo de gracia)
Presencia Opcional
Tipo Cadena
Valores válidos Una expresión de intervalo de tiempo o una referencia a una variable de flujo que contenga una expresión. Los periodos se pueden especificar con un número entero positivo seguido de un carácter que indique una unidad de tiempo, de la siguiente manera:
  • s = segundos
  • m = minutos
  • h = horas
  • d = días

<Type>

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

Describe si la política verifica un JWT firmado o un JWT cifrado. El elemento <Type> es opcional. Puedes usarlo para informar a los lectores de la configuración sobre si la política genera un JWT firmado o cifrado.

  • Si el elemento <Type> está presente:
    • Si el valor de <Type> es Signed, la política verifica un JWT firmado y el elemento <Algorithm> debe estar presente.
    • Si el valor de <Type> es Encrypted, la política verifica un JWT cifrado y el elemento <Algorithms> debe estar presente.
  • Si falta el elemento <Type>:
    • Si el elemento <Algorithm> está presente, la política asume que <Type> es Signed.
    • Si el elemento <Algorithms> está presente, la política asume que <Type> es Encrypted.
  • Si no se incluye <Algorithm> ni <Algorithms>, la configuración no es válida.
Predeterminado N/A
Presencia Opcional
Tipo Cadena
Valores válidos Signed o Encrypted

Flow variables

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

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
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.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
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 JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, 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 DecodeJWT, 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.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.
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.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
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.
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.
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.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
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.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
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.
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.
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.

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 "InvalidToken"
JWT.failed Todas las políticas de JWT establecen la misma variable en caso de falla. JWT.failed = true

Ejemplo de respuesta de error

Códigos de error de políticas de JWT

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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>