Política VerifyJWT

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

Consulta la documentación de Apigee Edge.

Qué

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.

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.

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.

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

Cómo

Si la política verifica un JWT firmado o cifrado, depende del elemento que utilices 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 cifrado.

Vídeo

Vea un breve vídeo sobre cómo verificar la firma de un JWT.

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.

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

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

{
  "typ" : "JWT",
  "alg" : "RS256"
}

{
  "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."
}

{
  "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."
}

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:

• <SecretKey>
• <PublicKey>

El elemento que uses dependerá del algoritmo elegido, tal como se muestra en la siguiente tabla:

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

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

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>

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:

• <PrivateKey>
• <SecretKey>
• <PasswordKey>
• <DirectKey>

El elemento que uses dependerá del algoritmo de cifrado de claves elegido, tal como se muestra en la siguiente tabla:

<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

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

<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>

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

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

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

<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 de cifrado de claves que se debe haber usado al crear el JWT cifrado. También especifica de forma opcional el algoritmo de cifrado del contenido.

Elementos secundarios de <Algorithms>

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

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.

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.

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

El elemento <Claim> acepta estos atributos:

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

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 nombre/valor de las reclamaciones adicionales especificados y que los valores de las reclamaciones confirmadas coincidan.

Una reclamación adicional usa un nombre que no es uno de los nombres de reclamación 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.

El elemento <Claim> acepta estos atributos:

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

<CustomClaims>

Nota: Actualmente, se inserta un elemento CustomClaims cuando añades 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.

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

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

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

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

<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 incluida, 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>.

<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 los siguientes:

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

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

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

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

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

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

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

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

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

<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 envías 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..."

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

<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 el desfase del reloj 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 no validez anterior (la reclamación nbf). Por ejemplo, si el tiempo permitido se configura como 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.

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

Variables de flujo

Si se verifica correctamente, las políticas Verificar JWT y Decodificar JWT definen 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 la variable de contexto denominada jwt.jwt-parse-token.decoded.claim.sub. (Para que sea retrocompatible, también estará disponible en jwt.jwt-parse-token.claim.subject).

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas y Cómo gestionar los errores.

Errores de tiempo de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Ejemplo de respuesta de error

Para gestionar los errores, la práctica recomendada es interceptar la parte errorcode de la respuesta de error. No te fíes del texto de faultstring, ya que podría cambiar.

Regla de error de ejemplo

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