Política de VerifyJWT

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

Qué

Verifica la firma en un 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, luego, que el JWT esté son válidos según el tiempo de vencimiento y no antes si están presentes. De forma opcional, la política también puede verificar los valores de reclamaciones específicas en el JWT, como el asunto, la entidad emisora, el público o el valor de las reclamaciones adicionales.

Si el JWT se verifica y es válido, todas las reclamaciones incluidas en el JWT se extraen en variables de contexto para que las usen las condiciones o políticas posteriores, y se permite continuar con la solicitud. Si la firma JWT no se puede verificar o si el JWT no es válido debido a una de las marcas de tiempo, se detiene todo el procesamiento y se 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
• Verifica un JWT firmado con el algoritmo RS256

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 para decodificar y evaluar el JWT, como dónde encontrar el JWT (en una variable de flujo especificada en el elemento Source), el de firma, dónde encontrar la clave secreta (almacenada en una variable de flujo de Edge, que podría se recuperaron del KVM de Edge, por ejemplo), y un conjunto de reclamaciones obligatorias y sus de salida.

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

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

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.

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

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

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

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

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.

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.

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

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

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

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

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

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

<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é el JWKS durante un período de 300 segundos. Cuando vence la caché, Edge recupera el JWKS otra vez.

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

<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. Solo uso cuando el algoritmo es HS256, HS384 o HS512.

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

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

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

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

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.

Errores en la implementación

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

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.

Ejemplo de respuesta de error

Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

Ejemplo de regla de falla

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>