Règle VerifyJWT

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Quoi

Vérifie un jeton JWT signé ou déchiffre et vérifie un jeton JWT chiffré en provenance de clients ou d'autres systèmes. Cette règle extrait également les revendications des variables de contexte, afin que les règles ou conditions ultérieures puissent examiner ces valeurs pour prendre des décisions d'autorisation ou de routage. Consultez la section Présentation des règles JWS et JWT pour une présentation détaillée.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

Lorsque cette règle s'exécute, et dans le cas d'un jeton JWT signé, Apigee vérifie la signature du jeton JWT à l'aide de la clé de validation fournie. Dans le cas d'un jeton JWT chiffré, Apigee déchiffre le jeton JWT à l'aide de la clé de déchiffrement. Dans les deux cas, Apigee vérifie ensuite la validité du jeton JWT en fonction du délai d'expiration et du délai de rigueur, s'ils sont précisés. La règle peut éventuellement vérifier les valeurs de revendications spécifiques sur le jeton JWT, telles que l'objet, l'émetteur, la cible, ou la valeur de revendications supplémentaires.

Si le jeton JWT contrôlé est validé, toutes les revendications qu'il contient sont extraites dans des variables de contexte pour être utilisées par les règles ou conditions suivantes, et la requête est autorisée à s'exécuter. Si la signature JWT ne peut pas être validée ou si le jeton JWT n'est pas valide en raison de l'un des horodatages, l'ensemble du traitement s'arrête et une erreur est renvoyée dans la réponse.

Pour en savoir plus sur les composants d'un jeton JWT, ainsi que sur la façon dont ceux-ci sont chiffrés et signés, consultez la RFC7519.

Comment

Le fait que la règle vérifie ou non un jeton JWT signé ou chiffré dépend de l'élément que vous utilisez pour spécifier l'algorithme qui vérifie le jeton JWT :

• Si vous utilisez l'élément <Algorithm>, la règle va vérifier un jeton JWT signé.
• Si vous utilisez l'élément <Algorithms>, la règle va vérifier un jeton JWT chiffré.

Vidéo

Regardez une courte vidéo pour apprendre à valider la signature d'un jeton JWT.

Vérifier un jeton JWT signé

Cette section explique comment vérifier un jeton JWT signé. Pour un jeton JWT signé, utilisez l'élément <Algorithm> pour spécifier l'algorithme de signature de la clé.

Exemples avec un jeton JWT signé

Les exemples suivants montrent comment vérifier un jeton JWT signé.

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

Les exemples ci-dessus utilisent l'élément <Algorithm>. Ils vérifient donc un jeton JWT signé. L'élément <PrivateKey> spécifie la clé utilisée pour signer le jeton JWT. Il existe également d'autres éléments de clé. Celui que vous allez utiliser dépend de l'algorithme spécifié par la valeur de <Algorithm>, comme décrit dans la section suivante.

Définir les éléments de clé pour vérifier un jeton JWT signé

Les éléments suivants spécifient la clé utilisée pour vérifier un jeton JWT signé :

• <SecretKey>
• <PublicKey>

L'élément que vous allez utiliser dépend de l'algorithme choisi, comme indiqué dans le tableau suivant :

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

Vérifier un jeton JWT chiffré

Cette section explique comment vérifier un jeton JWT chiffré. Pour un jeton JWT chiffré, utilisez l'élément <Algorithms> pour spécifier les algorithmes de signature de la clé et du contenu.

Exemple avec un jeton JWT chiffré

L'exemple suivant montre comment vérifier un jeton JWT chiffré (avec <Type> défini sur Encrypted), dans lequel :

• la clé est chiffrée avec l'algorithme RSA-OAEP-256 ;
• le contenu est chiffré avec l'algorithme 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>

L'exemple ci-dessus utilise l'élément <Algorithms>. Il vérifie donc un jeton JWT chiffré. L'élément <PrivateKey> spécifie la clé qui sera utilisée pour déchiffrer le jeton JWT. Il existe également d'autres éléments de clé. Celui que vous allez utiliser dépend de l'algorithme spécifié par la valeur de <Algorithms>, comme décrit dans la section suivante.

Définir les éléments de clé pour vérifier un jeton JWT chiffré

Les éléments suivants spécifient la clé utilisée pour vérifier un jeton JWT chiffré :

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

L'élément que vous allez utiliser dépend de l'algorithme de chiffrement de clé choisi, comme indiqué dans le tableau suivant :

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

Pour en savoir plus sur les conditions requises par les clés, consultez la section À propos des algorithmes de chiffrement de signature.

Documentation de référence des éléments

La documentation de référence de la règle décrit les éléments et les attributs de la règle VerifyJWT.

Remarque : La configuration diffère légèrement selon l'algorithme de chiffrement que vous utilisez. Référez-vous aux échantillons pour obtenir des exemples illustrant des configurations pour des cas d'utilisation spécifiques.

Attributs qui s'appliquent à l'élément de premier niveau

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

Les attributs suivants sont communs à tous les éléments parents de la règle.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Utilisez-le, en plus de l'attribut "name", pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<Algorithm>

<Algorithm>HS256</Algorithm>

Spécifie l'algorithme de chiffrement utilisé pour vérifier le jeton. Utilisez l'élément <Algorithm> pour vérifier un jeton JWT signé.

Les algorithmes RS*/PS*/ES* utilisent une paire de clés publique/secrète, tandis que les algorithmes HS* utilisent une clé secrète partagée. Consultez également À propos des algorithmes de chiffrement de signature.

Vous pouvez spécifier plusieurs valeurs séparées par une virgule. Par exemple, "HS256, HS512" ou "RS256, PS256". Cependant, vous ne pouvez pas associer des algorithmes HS* ou des algorithmes ES* à d'autres algorithmes, car ils exigent un type de clé spécifique. Vous pouvez combiner les algorithmes RS* et PS*.

<Algorithms>

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

Utilisez l'élément <Algorithms> pour vérifier un jeton JWT chiffré. Cet élément spécifie l'algorithme cryptographique pour la clé de chiffrement qui doit avoir été utilisée lors de la création du jeton JWT chiffré. Il spécifie également, si nécessaire, l'algorithme de chiffrement du contenu.

Éléments enfants de <Algorithms>

Le tableau suivant fournit une description détaillée des éléments enfants de <Algorithms> :

La validation échouera si :

• L'algorithme indiqué dans la propriété alg de l'en-tête du jeton JWT chiffré est différent de l'algorithme de chiffrement de clé spécifié ici dans l'élément <Key>.
• La règle spécifie un élément <Content>, et l'algorithme affirmé dans la propriété enc de l'en-tête du jeton JWT chiffré est différent de celui spécifié dans l'élément <Content>.

Par exemple, pour vérifier un jeton JWT chiffré et vérifier que l'algorithme de la clé est RSA-OAEP-256 et que l'algorithme de contenu est A128GCM :

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

Inversement, pour vérifier un jeton JWT chiffré et vérifier que l'algorithme de la clé est RSA-OAEP-256, et ne pas appliquer de contrainte sur l'algorithme de contenu :

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

Algorithmes de chiffrement de clé

Le tableau suivant répertorie les algorithmes disponibles pour le chiffrement de clé, ainsi que le type de clé que vous devez spécifier pour valider un jeton JWT à l'aide de l'algorithme de chiffrement de la clé.

Consultez la section Vérifier un jeton JWT chiffré pour accéder à un exemple utilisant l'algorithme de chiffrement de clé RSA-OAEP-256, ce qui implique d'utiliser l'élément <PrivateKey>.

Algorithmes de chiffrement de contenu

La règle VerifyJWT ne nécessite pas de spécifier un algorithme de chiffrement du contenu. Si vous souhaitez spécifier l'algorithme utilisé pour le chiffrement du contenu, utilisez l'élément enfant <Content> de l'élément <Algorithms>.

Quel que soit l'algorithme de chiffrement de clé, les algorithmes suivants, tous symétriques et AES, sont compatibles avec le chiffrement de contenu :

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM
• A192GCM
• A256GCM

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

La règle vérifie que la revendication d'audience du jeton JWT correspond à la valeur spécifiée dans la configuration. En l'absence de correspondance, la règle génère une erreur. Cette revendication identifie les destinataires du jeton JWT. Il s'agit de l'une des revendications enregistrées et mentionnées dans le document 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'/>

Vérifie que la charge utile JWT contient les revendications supplémentaires spécifiées, et que les valeurs de revendication déclarées correspondent.

Une revendication supplémentaire utilise un nom qui ne correspond pas à l'un des noms de revendication JWT standards enregistrés. La valeur d'une revendication supplémentaire peut être une chaîne, un nombre, une valeur booléenne, un mappage ou un tableau. Un mappage est simplement un ensemble de paires nom/valeur. La valeur d'une revendication de l'un de ces types peut être spécifiée explicitement dans la configuration de la règle ou indirectement via une référence à une variable de flux.

L'élément <Claim> utilise les attributs suivants :

• name : (obligatoire) nom de la revendication.
• ref (facultatif) : nom d'une variable de flux. Si elle est présente, la règle utilise la valeur de cette variable comme revendication. Si un attribut ref et une valeur de revendication explicite sont spécifiés, la valeur explicite est la valeur par défaut, et est utilisée si la variable de flux référencée n'est pas résolue.
• type : (facultatif) au choix : chaîne (par défaut), nombre, valeur booléenne ou mappage
• array : (facultatif) défini sur true pour indiquer que la valeur est un tableau de types. Valeur par défaut : "false".

Lorsque vous incluez l'élément <Claim>, les noms des revendications sont définis de manière statique lorsque vous configurez la règle. Vous pouvez également transmettre un objet JSON afin de spécifier les noms des revendications. Étant donné que l'objet JSON est transmis en tant que variable, les noms des revendications sont déterminés au moment de l'exécution.

Exemple :

<AdditionalClaims ref='json_claims'/>

Où la variable json_claims contient un objet JSON au format :

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

Vérifie que l'en-tête JWT contient la ou les paires nom/valeur de revendication supplémentaires spécifiées et que les valeurs de revendication déclarées correspondent.

Une revendication supplémentaire utilise un nom qui ne correspond pas à l'un des noms de revendication JWT standards enregistrés. La valeur d'une revendication supplémentaire peut être une chaîne, un nombre, une valeur booléenne, un mappage ou un tableau. Un mappage est simplement un ensemble de paires nom/valeur. La valeur d'une revendication de l'un de ces types peut être spécifiée explicitement dans la configuration de la règle ou indirectement via une référence à une variable de flux.

L'élément <Claim> utilise les attributs suivants :

• name : (obligatoire) nom de la revendication.
• ref (facultatif) : nom d'une variable de flux. Si elle est présente, la règle utilise la valeur de cette variable comme revendication. Si un attribut ref et une valeur de revendication explicite sont spécifiés, la valeur explicite est la valeur par défaut, et est utilisée si la variable de flux référencée n'est pas résolue.
• type : (facultatif) au choix : chaîne (par défaut), nombre, valeur booléenne ou mappage
• array : (facultatif) défini sur true pour indiquer que la valeur est un tableau de types. Valeur par défaut : "false".

<CustomClaims>

Remarque : Actuellement, un élément CustomClaims est inséré lorsque vous ajoutez une nouvelle règle GenerateJWT via l'interface utilisateur. Cet élément n'est pas fonctionnel et est ignoré. L'élément correct à utiliser à la place est <AdditionalClaims>. L'interface utilisateur sera mise à jour pour insérer les éléments corrects ultérieurement.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Vérifie que le jeton JWT possède la revendication jti spécifique. Lorsque la valeur textuelle et l'attribut "ref" sont tous deux vides, la règle génère un jti contenant un UUID aléatoire. La revendication de l'ID JWT (jti) est un identifiant unique du jeton JWT. Pour en savoir plus sur jti, consultez le document RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Définissez la valeur sur "false" si vous souhaitez que la règle génère une erreur lorsqu'un en-tête répertorié dans l'en-tête crit du jeton JWT n'est pas répertorié dans l'élément <KnownHeaders>. Définissez la valeur sur "true" pour que la règle VerifyJWT ignore l'en-tête crit.

Vous devez définir cet élément sur "true" si vous vous trouvez dans un environnement de test et que vous n'êtes pas encore prêt à gérer une défaillance sur un en-tête manquant.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Définissez la valeur sur "false" (valeur par défaut) si vous souhaitez que la règle génère une erreur lorsqu'un jeton JWT contient une revendication iat (Issued at) qui spécifie un horaire ultérieur. Définissez la valeur sur "true" pour que la règle ignore iat lors de la validation.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Définissez la valeur sur "false" si vous souhaitez que la règle génère une erreur lorsqu'une variable référencée dans la règle ne peut être résolue. Définissez la valeur sur "true" pour traiter toute variable irrésolue comme une chaîne vide (null).

<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 règle vérifie que l'émetteur du jeton JWT (la revendication iss) correspond à la chaîne spécifiée dans l'élément de configuration. La revendication iss est l'une des revendications enregistrées mentionnées dans la RFC 7519 de l'IETF.

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref='variable_containing_headers'/>

La règle GenerateJWT utilise l'élément <CriticalHeaders> pour renseigner l'en-tête crit dans un jeton JWT. Exemple :

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

S'il existe, la règle VerifyJWT examine l'en-tête crit du jeton JWT et vérifie pour chaque en-tête répertorié que l'élément <KnownHeaders> le répertorie également. L'élément <KnownHeaders> peut contenir un sur-ensemble des éléments répertoriés dans crit. Il n'est nécessaire que tous les en-têtes répertoriés dans crit soient répertoriés dans l'élément <KnownHeaders>. Tout en-tête identifié par la règle dans crit et qui ne figure pas dans <KnownHeaders> entraîne l'échec de la règle VerifyJWT.

Vous pouvez éventuellement configurer la règle VerifyJWT pour ignorer l'en-tête crit en définissant l'élément <IgnoreCriticalHeaders> sur true.

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

Configure la règle VerifyJWT pour vérifier que la durée de vie d'un jeton ne dépasse pas un seuil spécifié. Vous pouvez spécifier le seuil en utilisant un nombre suivi d'un caractère afin d'indiquer le nombre de secondes, de minutes, d'heures, de jours ou de semaines. Les caractères suivants sont valides :

• s - secondes
• m - minutes
• h - heures
• d - jours
• w - semaines

Par exemple, vous pouvez spécifier l'une des valeurs suivantes : 120s, 10m, 1h, 7d, 3w.

La règle calcule la durée de vie réelle du jeton en soustrayant la valeur (nbf) de la valeur d'expiration (exp). Si exp ou nbf est manquant, la règle génère une erreur. Si la durée de vie du jeton dépasse la période spécifiée, la règle génère une erreur.

Vous pouvez définir l'attribut facultatif useIssueTime sur true pour utiliser la valeur iat au lieu de la valeur nbf lors du calcul de la durée de vie du jeton.

L'utilisation de l'élément MaxLifespan est facultative. Si vous utilisez cet élément, vous ne pouvez l'utiliser qu'une seule fois.

<PrivateKey>

Utilisez cet élément pour spécifier la clé privée pouvant être utilisée pour vérifier un jeton JWT chiffré avec un algorithme asymétrique. Vous trouverez ci-dessous une description des éléments enfants possibles.

<Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Un enfant de l'élément <PrivateKey>. Spécifie le mot de passe que la règle doit utiliser pour déchiffrer la clé privée, si nécessaire, lors de la vérification d'un jeton JWT chiffré. Utilisez l'attribut ref pour transmettre le mot de passe dans une variable de flux.

<Value>

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

Enfant de l'élément <PrivateKey>. Spécifie une clé privée encodée au format PEM que la règle utilisera pour vérifier un jeton JWT chiffré. Utilisez l'attribut ref pour transmettre la clé dans une variable de flux.

<PublicKey>

Spécifie la source de la clé publique utilisée pour valider un jeton JWT signé avec un algorithme asymétrique. Les algorithmes acceptés sont RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512. Vous trouverez ci-dessous une description des éléments enfants possibles.

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
cert data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

Un enfant de l'élément <PublicKey>. Spécifie le certificat signé utilisé comme source de la clé publique. Utilisez l'attribut ref pour transmettre le certificat signé dans une variable de flux ou spécifiez directement le certificat encodé au format PEM.

<JWKS>

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

Un enfant de l'élément <PublicKey>. Spécifie un JWKS en tant que source de clés publiques. Il s'agit d'une liste de clés au format décrit dans IETF RFC 7517 – JSON Web Key (JWK).

Si le jeton JWT entrant a un ID de clé présent dans le JWKS, la règle utilise la clé publique appropriée pour valider la signature JWT. Pour en savoir plus sur cette fonctionnalité, consultez la section Utiliser un ensemble de clés Web JSON (JWKS) pour valider un jeton JWT.

Si vous récupérez la valeur à partir d'une URL publique, Apigee met en cache le JWKS pendant une période de 300 secondes. Lorsque le cache expire, Apigee récupère à nouveau le 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>

Un enfant de l'élément <PublicKey>. Spécifie la clé publique à utiliser pour valider la signature d'un jeton JWT signé. Utilisez l'attribut ref pour transmettre la clé dans une variable de flux ou spécifiez directement la clé encodée au format PEM.

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

L'élément <RequiredClaims> est facultatif. Il spécifie une liste de noms de revendications, séparés par une virgule, qui doivent être présents dans la charge utile JWT lors de la validation d'un jeton JWT. L'élément s'assure que le jeton JWT présenté contient les revendications requises mais ne valide pas le contenu des revendications. Si l'une des revendications listées n'est pas présente, la règle VerifyJWT génère une erreur au moment de l'exécution.

<SecretKey>

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

L'élément SecretKey est facultatif. Spécifie la clé secrète à utiliser lors de la vérification d'un jeton JWT signé utilisant un algorithme symétrique (HS*) ou lors de la vérification d'un jeton JWT chiffré utilisant un algorithme symétrique (AES) pour le chiffrement de clé.

Enfants de <SecretKey>

Le tableau suivant fournit une description des éléments enfants et des attributs de : <SecretKey>

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

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

<source>

<Source>jwt-variable</Source>

Le cas échéant, spécifie la variable de flux dans laquelle la règle s'attend à trouver le jeton JWT à valider.

Avec cet élément, vous pouvez configurer la règle pour récupérer le jeton JWT à partir d'une variable de paramètre de formulaire, de requête ou de toute autre variable. Lorsque cet élément est présent, la règle ne supprime aucun préfixe Bearer qui pourrait être présent. Si la variable n'existe pas ou si la règle ne trouve pas de jeton JWT dans la variable spécifiée, elle renvoie une erreur.

Par défaut, lorsqu'aucun élément <Source> n'est présent, la règle récupère le jeton JWT en lisant la variable request.header.authorization et en supprimant le préfixe Bearer. Si vous transmettez le jeton JWT dans l'en-tête Autorisation en tant que jeton de support (avec le préfixe Bearer), ne spécifiez pas l'élément <Source> dans la configuration de la règle. Par exemple, vous utiliseriez aucun élément <Source> dans la configuration de la règle si vous transmettez le jeton JWT dans l'en-tête Autorisation de la manière suivante :

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 règle vérifie que le sujet du jeton JWT (la revendication sub) correspond à la chaîne spécifiée dans la configuration de la règle. La revendication sub est l'une des revendications enregistrées décrites dans la 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>
  

Le "délai de grâce" pour les horaires, afin de tenir compte du décalage horaire entre l'émetteur et le vérificateur d'un jeton JWT. Cela s'applique à la fois à l'expiration (l'attribut exp) et à la date d'avant (l'attribut nbf). Par exemple, si l'intervalle de temps est configuré sur 30s, un jeton JWT expiré sera considéré comme valide pendant les 30 secondes qui suivent la déclaration d'expiration. Les messages antérieurs à l'horaire sont évalués de la même manière.

<Type>

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

Décrit si la règle vérifie un jeton JWT signé ou un jeton JWT chiffré. L'élément <Type> est facultatif. Vous pouvez l'utiliser pour indiquer aux lecteurs de la configuration que le jeton JWT généré par la règle est un jeton signé ou un jeton chiffré.

• Si l'élément <Type> est présent :
  • Si la valeur de <Type> est Signed, la règle vérifie un jeton JWT signé et l'élément <Algorithm> doit être présent.
  • Si la valeur de <Type> est Encrypted, la règle vérifie un jeton JWT chiffré et l'élément <Algorithms> doit être présent.
• Si l'élément <Type> est absent :
  • Si l'élément <Algorithm> est présent, la règle suppose que <Type> est défini sur Signed.
  • Si l'élément <Algorithms> est présent, la règle suppose que <Type> est défini sur Encrypted.
• Si ni <Algorithm>, ni <Algorithms> ne sont présents, la configuration n'est pas valide.

Variables de flux

En cas de réussite, les règles Verify JWT et Decode JWT définissent les variables de contexte en fonction du modèle suivant :

jwt.{policy_name}.{variable_name}

Par exemple, si le nom de la règle est jwt-parse-token, la règle stocke le sujet spécifié dans le jeton JWT dans la variable de contexte nommée jwt.jwt-parse-token.decoded.claim.sub. (Pour assurer la rétrocompatibilité, il sera également disponible dans jwt.jwt-parse-token.claim.subject)

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

Exemple de règle de défaillance

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