Règle VerifyJWT

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

Consultez la documentation d'Apigee Edge.

icône de la règle

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 :

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

Algorithme HS256

Cet exemple de règle vérifie un jeton JWT signé avec l'algorithme de chiffrement HMAC HS256 à l'aide d'une somme de contrôle SHA-256. Le jeton JWT est transmis dans la requête de proxy à l'aide d'un paramètre de formulaire nommé jwt. La clé est contenue dans une variable nommée private.secretkey. Regardez la vidéo ci-dessus pour voir un exemple complet, y compris pour découvrir comment envoyer une demande à la stratégie.

La configuration de la règle inclut les informations nécessaires à Apigee pour décoder et évaluer le jeton JWT, par exemple l'emplacement du jeton JWT (dans une variable de flux spécifiée dans l'élément source), l'algorithme de signature requis, l'emplacement de la clé secrète (stockée dans une variable de flux Apigee, qui peut avoir été récupérée à partir de la KVM Apigee, par exemple), ainsi qu'un ensemble de revendications requises et leurs valeurs.

<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 règle écrit sa sortie dans des variables de contexte afin que les règles ou les conditions ultérieures du proxy d'API puissent examiner ces valeurs. Pour obtenir la liste des variables définies par cette règle, consultez la section Variables de flux.

Algorithme RS256

Cet exemple de règle vérifie un jeton JWT signé avec l'algorithme RS256. Pour procéder à la vérification, vous devez fournir la clé publique. Le jeton JWT est transmis dans la requête de proxy à l'aide d'un paramètre de formulaire nommé jwt. La clé publique se trouve dans une variable nommée public.publickey. Regardez la vidéo ci-dessus pour voir un exemple complet, y compris pour découvrir comment envoyer une demande à la stratégie.

Consultez la documentation de référence sur les éléments pour en savoir plus sur les exigences et les options de chaque élément dans cet exemple de règle.

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

Pour la configuration ci-dessus, un jeton JWT avec cet en-tête…

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

Et cette charge utile…

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

…sera considéré comme valide si la signature peut être validée avec la clé publique fournie.

Un jeton JWT avec le même en-tête, mais avec cette charge utile…

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

…sera considéré comme non valide, même si la signature peut être validée, car la revendication "sub" incluse dans le jeton JWT ne correspond pas à la valeur de l'élément "Subject" spécifiée dans la configuration de la règle.

La règle écrit sa sortie dans des variables de contexte afin que les règles ou les conditions ultérieures du proxy d'API puissent examiner ces valeurs. Pour obtenir la liste des variables définies par cette règle, consultez la section Variables de flux.

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

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

Algorithme Éléments clés
HS* 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>
RS*, ES*, PS* 
<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

ou :

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

ou :

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>
* Pour en savoir plus sur les conditions requises par les clés, consultez la section À propos des algorithmes de chiffrement de signature.

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

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

Algorithme Éléments clés
RSA-OAEP-256 
<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

Remarque : La variable que vous spécifiez doit pointer vers une clé privée RSA au format PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Remarque : La variable que vous spécifiez doit pointer vers une clé privée à courbe elliptique au format PEM.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>
dir 
<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

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.

Attribut Description Par défaut Presence
nom Nom interne de la stratégie. Les caractères que vous pouvez utiliser dans le nom se limitent à : A-Z0-9._\-$ %. L'interface utilisateur Apigee applique cependant des restrictions supplémentaires, telles que la suppression automatique des caractères qui ne sont pas alphanumériques.

Vous pouvez également utiliser l'élément <displayname></displayname> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

 N/A Obligatoire
continueOnError Définissez sur false pour afficher une erreur en cas d'échec d'une stratégie. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle.

 false Facultatif
activé Définissez la valeur sur true pour appliquer la stratégie.

Définissez la valeur sur false pour "désactiver" la stratégie. La stratégie ne sera pas appliquée même si elle reste associée à un flux.

 true Facultatif
async Cet attribut est obsolète. false Obsolète

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

Par défaut Si vous omettez cet élément, la valeur de l'attribut de nom de la stratégie est utilisée.
Presence Facultatif
Type Chaîne

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

Par défaut N/A
Presence Obligatoire
Type Chaîne de valeurs séparées par une virgule
Valeurs valides HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

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

Par défaut N/A
Presence Obligatoire pour valider un jeton JWT chiffré
Type Complexe

Éléments enfants de <Algorithms>

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

Élément enfant Obligatoire ? Description
<Key> Obligatoire Spécifie l'algorithme de chiffrement de la clé.
<Content> Facultatif Spécifie l'algorithme de chiffrement du contenu.

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

Valeur de <Key> (algorithme de chiffrement de clé) Élément de clé requis pour la vérification
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

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.

Par défaut N/A
Presence Facultatif
Type Chaîne
Valeurs valides Une variable ou une chaîne du flux qui identifie la cible.

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

Par défaut N/A
Presence Facultatif
Type Chaîne, nombre, booléen ou mappage
Array Définissez la valeur sur true pour indiquer que la valeur est un tableau de types. Valeur par défaut : "false"
Valeurs valides Toute valeur que vous souhaitez utiliser dans une revendication supplémentaire.

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.

Par défaut N/A
Presence Facultatif
Type

Chaîne (par défaut), nombre, booléen ou mappage.

Si aucune valeur n'est spécifiée, le type par défaut est "Chaîne".
Array Définissez la valeur sur true pour indiquer que la valeur est un tableau de types. Valeur par défaut : "false"
Valeurs valides Toute valeur que vous souhaitez utiliser dans une revendication supplémentaire.

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.

Par défaut N/A
Presence Facultatif
Type Chaîne ou référence.
Valeurs valides Chaîne ou nom d'une variable de flux contenant l'ID.

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

Par défaut false
Presence Facultatif
Type Booléen
Valeurs valides true ou false

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

Par défaut false
Presence Facultatif
Type Booléen
Valeurs valides True ou False

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

Par défaut false
Presence Facultatif
Type Booléen
Valeurs valides true ou false

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

Par défaut N/A
Presence Facultatif
Type Chaîne ou référence
Valeurs valides Tout

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

Par défaut N/A
Presence Facultatif
Type Tableau de chaînes séparées par une virgule
Valeurs valides Tableau ou nom d'une variable contenant le tableau.

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

Par défaut N/A
Presence Facultatif
Type Chaîne
Valeurs valides Référence de variable de flux

Remarque : Vous devez spécifier une variable de flux. Apigee rejettera la configuration d'une stratégie non valide dans laquelle le mot de passe est spécifié en texte brut. La variable de flux doit comporter le préfixe "private". Par exemple, private.mypassword.

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

Par défaut N/A
Presence Obligatoire pour valider un jeton JWT chiffré à l'aide d'un algorithme de chiffrement à clé asymétrique.
Type Chaîne
Valeurs valides Variable de flux contenant une chaîne représentant une valeur de clé privée RSA encodée au format PEM.

Remarque : La variable de flux doit comporter le préfixe "private". Par exemple, private.mykey.

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

Par défaut N/A
Presence Facultatif. Pour valider un jeton JWT signé avec un algorithme asymétrique, vous devez utiliser l'élément <Certificate>, l'élément <JWKS>, ou l'élément <Value> pour fournir la clé publique.
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

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

Par défaut N/A
Presence Facultatif. Pour valider un jeton JWT signé avec un algorithme asymétrique, vous devez utiliser l'élément <Certificate>, l'élément <JWKS>, ou l'élément <Value> pour fournir la clé publique.
Type Chaîne
Valeurs valides

Vous pouvez spécifier les JWKS de l'une des quatre manières suivantes :

  • Littéralement, sous forme de valeur texte :

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

  • Indirectement, avec l'attribut ref, en spécifiant une variable de flux :

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

    La variable référencée doit contenir une chaîne représentant un JWKS.

  • Indirectement via un URI statique, avec l'attribut uri :

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

  • Indirectement via un URI déterminé dynamiquement, avec l'attribut uriRef :

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

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

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.

Par défaut N/A
Presence Facultatif. Pour valider un jeton JWT signé avec un algorithme asymétrique, vous devez utiliser l'élément <Certificate>, l'élément <JWKS>, ou l'élément <Value> pour fournir la clé publique.
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

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

Par défaut N/A
Presence Facultatif
Type Chaîne
Valeurs valides Liste de noms de revendications séparés par une virgule.

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

Enfant Presence Description
codage (attribut) Facultatif

Spécifie le mode d'encodage de la clé dans la variable référencée. Par défaut, lorsqu'aucun attribut encoding n'est présent, l'encodage de la clé est traité comme étant UTF-8. Les valeurs valides pour l'attribut sont hexadécimal, base16, base64 ou base64url. Les valeurs d'encodage hexadécimales et base16 sont des synonymes.

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

Dans l'exemple ci-dessus, l'encodage étant hex, si le contenu de la variable private.secretkey est 494c6f766541504973, la clé est décodée comme un ensemble de 9 octets, qui sera 49 4c 6f 76 65 41 50 49 73 en hexadécimal.

Valeur (élément) Obligatoire

Clé secrète encodée. Spécifie la clé secrète qui sera utilisée pour vérifier la charge utile. Utilisez l'attribut ref pour fournir la clé indirectement via une variable, telle que private.secret-key.

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

Apigee applique un niveau de sécurité de clé minimal pour les algorithmes HS256/HS384/HS512. La longueur de clé minimale pour HS256 est de 32 octets, pour HS384 de 48 octets, et pour HS512 de 64 octets. L'utilisation d'une clé d'un niveau de sécurité inférieur entraîne une erreur d'exécution.

<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..."
Par défaut request.header.authorization (Consultez la remarque ci-dessus pour obtenir des informations importantes sur la valeur par défaut).
Presence Facultatif
Type Chaîne
Valeurs valides Nom de variable de flux Apigee

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

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

Par défaut N/A
Presence Facultatif
Type Chaîne
Valeurs valides Toute valeur unique identifiant un sujet.

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

Par défaut 0 seconde (aucun délai de grâce)
Presence Facultatif
Type Chaîne
Valeurs valides Expression de durée ou référence à une variable de flux contenant une expression. Les intervalles de temps peuvent être spécifiés par un entier positif suivi d'un caractère indiquant une unité de temps, comme suit :
  • s = secondes
  • m = minutes
  • h = heures
  • d = jours

<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.
Par défaut N/A
Presence Facultatif
Type Chaîne
Valeurs valides Signed ou Encrypted

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)

Nom de la variable Description
claim.audience Revendication d'audience JWT. Cette valeur peut être une chaîne ou un tableau de chaînes.
claim.expiry Date/heure d'expiration, exprimées en millisecondes depuis l'epoch.
claim.issuedat Date à laquelle le jeton a été émis, exprimée en millisecondes depuis l'epoch.
claim.issuer Revendication d'émetteur JWT.
claim.notbefore Si le jeton JWT inclut une revendication nbf, cette variable contiendra la valeur, exprimée en millisecondes depuis l'epoch.
claim.subject Revendication de sujet JWT.
claim.name Valeur de la revendication nommée (standard ou supplémentaire) dans la charge utile. L'un d'eux sera défini pour chaque revendication dans la charge utile.
decoded.claim.name Valeur analysable par JSON de la revendication nommée (standard ou supplémentaire) dans la charge utile. Une variable est définie pour chaque revendication de la charge utile. Par exemple, vous pouvez utiliser decoded.claim.iat pour récupérer l'heure d'émission du jeton JWT, exprimée en secondes depuis l'epoch. Bien que vous puissiez également utiliser les variables de flux claim.name, il s'agit de la variable recommandée pour accéder à une revendication.
decoded.header.name Valeur analysable par JSON d'un en-tête dans la charge utile. Une variable est définie pour chaque en-tête de la charge utile. Bien que vous puissiez également utiliser les variables de flux header.name, il s'agit de la variable recommandée pour accéder à un en-tête.
expiry_formatted Date/heure d'expiration, mise en forme en tant que chaîne lisible par l'humain. Exemple : 2017-09-28T21:30:45.000+0000
header.algorithm Algorithme de signature utilisé sur le jeton JWT. Par exemple, RS256, HS384, etc. Consultez la section Paramètre d'en-tête (algorithme) pour en savoir plus.
header.kid ID de clé, s'il est ajouté lorsque le jeton JWT a été généré. Pour vérifier un jeton JWT, consultez également la section "Utiliser un jeu de clés Web JSON (JWKS)" sur la page Présentation des règles JWT. Consultez la section Paramètre d'en-tête (ID de clé) pour en savoir plus.
header.type Sera défini sur JWT.
header.name Valeur de l'en-tête nommé (standard ou supplémentaire). L'un d'eux sera défini pour chaque en-tête supplémentaire dans la partie en-tête du jeton JWT.
header-json En-tête au format JSON.
is_expired True ou False
payload-claim-names Tableau des revendications acceptées par le jeton JWT.
payload-json
Charge utile au format JSON.
seconds_remaining Nombre de secondes avant l'expiration du jeton. Si le jeton a expiré, ce nombre est négatif.
time_remaining_formatted Temps restant avant l'expiration du jeton, mis en forme en tant que chaîne lisible par l'humain. Exemple : 00:59:59.926
valid Dans le cas de VerifyJWT, cette variable est true lorsque la signature est validée, et que l'heure actuelle est antérieure à l'expiration du jeton et postérieure à la valeur notBefore du jeton, si elles sont présentes. Sinon, la valeur est false.

Dans le cas de DecodeJWT, cette variable n'est pas définie.

Informations de référence sur les erreurs

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration 401 Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidIterationCount 401 The iteration count that was used in the encrypted JWT is not equal to the iteration count specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS in the <PublicKey> element is invalid. The reason could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint as a target.
steps.jwt.InvalidSaltLength 401 The salt length that was used in the encrypted JWT is not equal to the salt length specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
InvalidEmptyElement This error occurs if the <Source> element of the Verify JWT policy is empty. If present, it must be defined with an Apigee flow variable name.
InvalidPublicKeyValue If the value used in the child element <JWKS> of the <PublicKey> element does not use a valid format as specified in RFC 7517, the deployment will fail.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.

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

Variables Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "InvalidToken"
JWT.failed Toutes les règles JWT définissent la même variable en cas d'échec. JWT.failed = true

Exemple de réponse d'erreur

Codes d'erreur de la règle JWT

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>