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

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

 vrai Facultatif
async Cet attribut est obsolète. faux 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.
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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 faux
Présence 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 faux
Présence 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 faux
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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
Présence 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 Présence 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).
Présence 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
Présence 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)
Présence 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
Présence 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. 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. 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

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.

Code d'erreur État HTTP Se produit quand
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Se produit lorsque la règle de validation comporte plusieurs algorithmes.
steps.jwt.AlgorithmMismatch 401 L'algorithme spécifié dans la règle Generate ne correspond pas à celui attendu dans la règle Verify. Les algorithmes spécifiés doivent correspondre.
steps.jwt.FailedToDecode 401 La règle n'a pas pu décoder le jeton JWT. Le jeton JWT est peut-être corrompu.
steps.jwt.GenerationFailed 401 La règle n'a pas pu générer le jeton JWT.
steps.jwt.InsufficientKeyLength 401 Pour une clé inférieure à 32 octets pour l'algorithme HS256, inférieure à 48 octets pour l'algorithme HS386 et inférieure à 64 octets pour l'algorithme HS512.
steps.jwt.InvalidClaim 401 En cas de problème de revendication ou de revendication manquante, de problème d'en-tête ou d'en-tête manquant.
steps.jwt.InvalidConfiguration 401 Les éléments <Algorithm> et <Algorithms> sont présents.
steps.jwt.InvalidCurve 401 La courbe spécifiée par la clé n'est pas valide pour l'algorithme à courbe elliptique.
steps.jwt.InvalidIterationCount 401 Le nombre d'itérations utilisé dans le jeton JWT chiffré n'est pas égal au nombre d'itérations spécifié dans la configuration de la stratégie VerifyJWT. Cette méthode ne s'applique qu'aux jetons JWT utilisant <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 JSON non valide trouvé dans l'en-tête ou la charge utile.
steps.jwt.InvalidKeyConfiguration 401 La valeur JWKS de l'élément <PublicKey> n'est pas valide. Cela peut être dû au fait que le point de terminaison de l'URI JWKS n'est pas accessible à partir de l'instance Apigee. Testez la connectivité au point de terminaison en créant un proxy direct et en utilisant le point de terminaison JWKS comme cible.
steps.jwt.InvalidSaltLength 401 La longueur de salage utilisée dans le jeton JWT chiffré n'est pas égale à la longueur de salage spécifiée dans la configuration de la règle VerifyJWT. Cette méthode ne s'applique qu'aux jetons JWT utilisant <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 La clé spécifiée ne répond pas aux exigences.
steps.jwt.InvalidPrivateKey 401 La clé spécifiée ne répond pas aux exigences.
steps.jwt.InvalidPublicKey 401 La clé spécifiée ne répond pas aux exigences.
steps.jwt.InvalidSecretKey 401 La clé spécifiée ne répond pas aux exigences.
steps.jwt.InvalidToken 401 Cette erreur se produit en cas d'échec de la validation de la signature du jeton JWT.
steps.jwt.JwtAudienceMismatch 401 La revendication d'audience a échoué lors de la vérification du jeton.
steps.jwt.JwtIssuerMismatch 401 La revendication d'émetteur a échoué lors de la vérification du jeton.
steps.jwt.JwtSubjectMismatch 401 La revendication de sujet a échoué lors de la vérification du jeton.
steps.jwt.KeyIdMissing 401 La règle Verify utilise un JWKS en tant que source pour les clés publiques, mais le jeton JWT signé n'inclut pas la propriété kid dans l'en-tête.
steps.jwt.KeyParsingFailed 401 Impossible d'analyser la clé publique à partir des informations de clé fournies.
steps.jwt.NoAlgorithmFoundInHeader 401 Se produit lorsque le jeton JWT ne contient pas d'en-tête d'algorithme.
steps.jwt.NoMatchingPublicKey 401 La règle Verify utilise un JWKS en tant que source pour les clés publiques, mais le kid du jeton JWT signé n'est pas répertorié dans le JWKS.
steps.jwt.SigningFailed 401 Dans GenerateJWT, pour une clé inférieure à la taille minimale des algorithmes HS384 ou HS512
steps.jwt.TokenExpired 401 La règle tente de vérifier un jeton expiré.
steps.jwt.TokenNotYetValid 401 Le jeton n'est pas encore valide.
steps.jwt.UnhandledCriticalHeader 401 Un en-tête trouvé par la règle de vérification JWT dans l'en-tête crit n'est pas répertorié dans KnownHeaders.
steps.jwt.UnknownException 401 Une exception inconnue s'est produite.
steps.jwt.WrongKeyType 401 Type de clé spécifié incorrect. Par exemple, si vous spécifiez une clé RSA pour un algorithme à courbe elliptique ou une clé à courbe elliptique pour un algorithme RSA.

Erreurs de déploiement

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

Nom de l'erreur Cause Corriger
InvalidNameForAdditionalClaim Le déploiement échouera si la revendication utilisée dans l'élément enfant <Claim> de l'élément <AdditionalClaims> correspond à l'un des noms enregistrés suivants : kid, iss, sub, aud, iat, exp, nbf ou jti).
InvalidTypeForAdditionalClaim Si la revendication utilisée dans l'élément enfant <Claim> de l'élément <AdditionalClaims> n'est pas de type string, number, boolean ou map, le déploiement échouera.
MissingNameForAdditionalClaim Si le nom de la revendication n'est pas spécifié dans l'élément enfant <Claim> de l'élément <AdditionalClaims>, le déploiement échouera.
InvalidNameForAdditionalHeader Cette erreur se produit lorsque le nom de la revendication utilisé dans l'élément enfant <Claim> de l'élément <AdditionalClaims> est alg ou typ.
InvalidTypeForAdditionalHeader Si la revendication utilisée dans l'élément enfant <Claim> de l'élément <AdditionalClaims> n'est pas de type string, number, boolean ou map, le déploiement échouera.
InvalidValueOfArrayAttribute Cette erreur se produit lorsque la valeur de l'attribut de tableau dans l'élément enfant <Claim> de l'élément <AdditionalClaims> n'est pas définie sur true ou false.
InvalidValueForElement Si la valeur spécifiée dans l'élément <Algorithm> n'est pas une valeur acceptée, le déploiement échouera.
MissingConfigurationElement Cette erreur se produira si l'élément <PrivateKey> n'est pas utilisé avec les algorithmes de la famille RSA ou si l'élément <SecretKey> n'est pas utilisé avec les algorithmes de la famille HS.
InvalidKeyConfiguration Si l'élément enfant <Value> n'est pas défini dans les éléments <PrivateKey> ou <SecretKey>, le déploiement échouera.
EmptyElementForKeyConfiguration Si l'attribut "ref" de l'élément enfant <Value> des éléments <PrivateKey> ou <SecretKey> est vide ou non spécifié, le déploiement échouera.
InvalidConfigurationForVerify Cette erreur se produit si l'élément <Id> est défini dans l'élément <SecretKey>.
InvalidEmptyElement Cette erreur se produit si l'élément <Source> de la règle de vérification JWT est vide. S'il est présent, il doit être défini avec un nom de variable de flux Apigee.
InvalidPublicKeyValue Si la valeur utilisée dans l'élément enfant <JWKS> de l'élément <PublicKey> n'utilise pas un format valide tel que spécifié dans le document RFC 7517, le déploiement échouera.
InvalidConfigurationForActionAndAlgorithm Si l'élément <PrivateKey> est utilisé avec des algorithmes de la famille HS ou si l'élément <SecretKey> est utilisé avec des algorithmes de la famille RSA, le déploiement échouera.

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>