Política de VerifyJWT

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Qué

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

Cuando se ejecuta esta política, Edge verifica la firma de un JWT y comprueba que el JWT sea válido según los tiempos de vencimiento y no antes de que 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 muestra un error en la respuesta.

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

Video

Mira un breve video para aprender a verificar la firma en un JWT.

Ejemplos

Verifica un JWT firmado con el algoritmo HS256

En esta política de ejemplo, se verifica un JWT firmado con el algoritmo de encriptación HS256, HMAC mediante 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 Edge necesita decodificar y evaluar el JWT, como dónde encontrar el JWT (en una variable de flujo especificada en el elemento de origen), el algoritmo de firma requerido, dónde encontrar la clave secreta (almacenada en una variable de flujo de Edge, que podría haberse recuperado del KVM de Edge, 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 resultado en variables de contexto para que las políticas o condiciones posteriores en el proxy de API puedan examinar esos valores. Consulta Variables de flujo para obtener una lista de las variables que establece esta política.

Verifica un JWT firmado con el 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.

Configura los elementos clave

Los elementos que usas para especificar la clave que se usa para verificar el JWT dependen 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.

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 administración perimetral aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos.

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

No disponible Obligatorio
continueOnError Configúralo como false para devolver un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.

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

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

true Opcional
async Este atributo dejó de estar disponible. false Funciones obsoletas

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Además de usar el atributo de nombre para etiquetar la política en el editor de proxy de IU de administración con un nombre diferente y con lenguaje natural.

Valor predeterminado Si omites este elemento, se usa el valor del atributo de nombre de la política.
Presencia Opcional
Tipo String

<Algorithm>

<Algorithm>HS256</Algorithm>

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

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

Valor predeterminado No disponible
Presencia Obligatorio
Tipo String de valores separados por comas
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<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 No disponible
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 No disponible
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 No disponible
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 No disponible
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 transmitir una falla en un encabezado faltante.

Valor predeterminado false
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 false
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 false
Presencia Opcional
Tipo Booleano
Valores válidos True o False

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

La política verifica que la entidad emisora en el JWT coincida con la string especificada en el elemento de configuración. Un reclamo que identifica a la entidad emisora del JWT. Este es uno de los conjuntos de reclamaciones registradas que se mencionan en RFC7519.

Valor predeterminado No disponible
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 No disponible
Presencia Opcional
Tipo Arreglo de strings separadas por comas
Valores válidos Un arreglo o el nombre de una variable que contiene el arreglo.

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Especifica el certificado firmado que se usa para verificar la firma en el JWT. Usa el atributo ref para pasar el certificado firmado en una variable de flujo o especifica el certificado codificado con PEM directamente. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predeterminada No disponible
Presencia Para verificar un JWT firmado con un algoritmo RSA, debes usar los elementos Certificado, JWKS o Valor.
Tipo String
Valores válidos Una string o variable de flujo.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Especifica un valor en formato JWKS (RFC 7517) que contiene un conjunto de claves públicas. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Si el JWT entrante tiene un ID de clave que está presente en el conjunto de JWKS, la política usará la clave pública correcta para verificar la firma de 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, Edge almacena en caché los JWKS durante un período de 300 segundos. Cuando venza la caché, Edge recuperará los JWKS.

Valor predeterminado No disponible
Presencia Para verificar un JWT con un algoritmo RSA, debes usar el elemento Certificado, JWKS o Valor.
Tipo String
Valores válidos Una variable de flujo, un valor de string o una URL.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Especifica la clave pública o el certificado público que se usa para verificar la firma en el JWT. Usa el atributo ref para pasar el certificado/la clave en una variable de flujo o especifica la clave codificada con PEM directamente. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Valor predeterminado No disponible
Presencia Para verificar un JWT firmado con un algoritmo RSA, debes usar los elementos Certificado, JWKS o Valor.
Tipo String
Valores válidos Una string o variable de flujo.

<SecretKey/Value>

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

Proporciona la clave secreta usada para verificar o firmar tokens con un algoritmo HMAC. Úsalo solo cuando el algoritmo sea HS256, HS384 o HS512.

Valor predeterminado No disponible
Presencia Obligatorio para los algoritmos HMAC.
Tipo String
Valores válidos

Para encoding, los valores válidos son hex, base16, base64 o base64url. Los valores de codificación hex y base16 son sinónimos.

Usa el atributo ref para pasar la clave en una variable de flujo.

Nota: Si es una variable de flujo, debe tener el prefijo “private”. Por ejemplo:private.mysecret

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

Predeterminada request.header.authorization (consulta la nota anterior para obtener información importante sobre el valor predeterminado).
Presencia Opcional
Tipo String
Valores válidos Un nombre de variable de flujo de Edge.

<Subject>

<Subject>subject-string-here</Subject>

La política verifica que el asunto en el JWT coincida con la string especificada en la configuración de la política. Esta reclamación identifica o emite una declaración sobre el tema del JWT. Este es uno de los conjuntos de reclamaciones estándar que se mencionan en RFC7519.

Valor predeterminado No disponible
Presencia Opcional
Tipo String
Valores válidos Cualquier valor que identifique de forma única a un asunto.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

El “período de gracia” de los horarios. Por ejemplo, si la asignación de tiempo se configura para que sean 60 segundos, un JWT vencido se tratará como válido para los 60 segundos después del vencimiento de la aserción. La hora anterior se evaluará de manera similar. La configuración predeterminada es de 0 segundos (sin período de gracia).

Valor predeterminado 0 segundos (sin período de gracia)
Presencia Opcional
Tipo String
Valores válidos Un valor o una referencia a una variable de flujo que contiene el valor. Los intervalos de tiempo se pueden especificar de la siguiente manera:
  • s = segundos
  • m = minutos
  • h = horas
  • d = días

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 ofrecer 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 el momento de emisión del JWT, expresado 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

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

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

Código de falla Estado de HTTP Ocurre cuando
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Se produce cuando la política de verificación tiene varios algoritmos.
steps.jwt.AlgorithmMismatch 401 El algoritmo especificado en la política de generación no coincide con el esperado en la política de verificación. Los algoritmos especificados deben coincidir.
steps.jwt.FailedToDecode 401 La política no pudo decodificar el JWT. Es posible que el JWT esté dañado.
steps.jwt.GenerationFailed 401 La política no pudo generar el JWT.
steps.jwt.InsufficientKeyLength 401 En el caso de las claves inferiores a 32 bytes para el algoritmo HS256, menos de 48 bytes para el algoritmo HS386 y menos de 64 bytes para el algoritmo HS512.
steps.jwt.InvalidClaim 401 Porque falta un reclamo o un reclamo, o bien el encabezado o el encabezado no coinciden.
steps.jwt.InvalidCurve 401 La curva especificada por la clave no es válida para el algoritmo de curva elíptica.
steps.jwt.InvalidJsonFormat 401 Se encontró un archivo JSON que no es válido en el encabezado o la carga útil.
steps.jwt.InvalidToken 401 Este error ocurre cuando falla la verificación de la firma del JWT.
steps.jwt.JwtAudienceMismatch 401 La reclamación del público falló en la verificación del token.
steps.jwt.JwtIssuerMismatch 401 La reclamación de la entidad emisora falló durante la verificación del token.
steps.jwt.JwtSubjectMismatch 401 La reclamación de la entidad falló durante la verificación del token.
steps.jwt.KeyIdMissing 401 La política Verificar usa un JWKS como fuente para las claves públicas, pero el JWT firmado no incluye una propiedad kid en el encabezado.
steps.jwt.KeyParsingFailed 401 No se pudo analizar la clave pública a partir de la información clave proporcionada.
steps.jwt.NoAlgorithmFoundInHeader 401 Ocurre cuando el JWT no contiene un encabezado de algoritmo.
steps.jwt.NoMatchingPublicKey 401 La política de verificación usa un JWKS como fuente para claves públicas, pero la propiedad kid en el JWT firmado no aparece en el JWKS.
steps.jwt.SigningFailed 401 En GenerateJWT, ocurre en el caso de una clave que es menor que el tamaño mínimo para los algoritmos HS384 o HS512.
steps.jwt.TokenExpired 401 La política intenta verificar un token vencido.
steps.jwt.TokenNotYetValid 401 El token aún no es válido.
steps.jwt.UnhandledCriticalHeader 401 Un encabezado que encontró la política de verificación de JWT en el encabezado crit no aparece en KnownHeaders.
steps.jwt.UnknownException 401 Se produjo una excepción desconocida.
steps.jwt.WrongKeyType 401 El tipo de clave especificado es incorrecto. Por ejemplo, si especificas una clave RSA para un algoritmo de curva elíptica o una clave de curva para un algoritmo de RSA.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa Corregir
InvalidNameForAdditionalClaim La implementación fallará si la reclamación que se usa en el elemento secundario <Claim> del elemento <AdditionalClaims> es uno de los siguientes nombres registrados: kid, iss, sub, aud, iat, exp, nbf o jti.
InvalidTypeForAdditionalClaim Si la reclamación que se usa en el elemento secundario <Claim> del elemento <AdditionalClaims> no es del tipo string, number, boolean ni map, la implementación fallará.
MissingNameForAdditionalClaim Si el nombre de la reclamación no se especifica en el elemento secundario <Claim> del elemento <AdditionalClaims>, la implementación fallará.
InvalidNameForAdditionalHeader Este error ocurre cuando el nombre de la reclamación utilizado en el elemento secundario <Claim> del elemento <AdditionalClaims> es alg o typ.
InvalidTypeForAdditionalHeader Si el tipo de reclamación que se usa en el elemento secundario <Claim> del elemento <AdditionalClaims> no es del tipo string, number, boolean ni map, la implementación fallará.
InvalidValueOfArrayAttribute Este error se produce cuando el valor del atributo de array en el elemento secundario <Claim> del elemento <AdditionalClaims> no se establece en true ni false.
InvalidValueForElement Si el valor especificado en el elemento <Algorithm> no es un valor admitido, la implementación fallará.
MissingConfigurationElement Este error se producirá si no se usa el elemento <PrivateKey> con los algoritmos de la familia RSA o si no se usa el elemento <SecretKey> con los algoritmos de la familia HS.
InvalidKeyConfiguration Si el elemento secundario <Value> no está definido en los elementos <PrivateKey> o <SecretKey>, la implementación fallará.
EmptyElementForKeyConfiguration Si el atributo ref del elemento secundario <Value> de los elementos <PrivateKey> o <SecretKey> está vacío o no se especifica, la implementación fallará.
InvalidConfigurationForVerify Este error se produce si el elemento <Id> se define dentro del elemento <SecretKey>.
InvalidEmptyElement Este error se produce si el elemento <Source> de la política Verificar JWT está vacío. Si está presente, debe definirse con un nombre de variable de flujo de Edge.
InvalidPublicKeyValue Si el valor que se usa en el elemento secundario <JWKS> del elemento <PublicKey> no usa un formato válido como se especifica en RFC 7517, la implementación fallará.
InvalidConfigurationForActionAndAlgorithm Si el elemento <PrivateKey> se usa con los algoritmos de la familia HS o el elemento <SecretKey> con los algoritmos de la familia RSA, la implementación fallará.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "TokenExpired"
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 "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>