Règle VerifyJWT

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X.
En savoir plus

Quoi

Valide la signature d'un jeton JWT envoyé par des 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.

Lorsque cette règle s'exécute, Edge vérifie la signature d'un JWT et vérifie que le JWT est valide selon la date d'expiration ou non antérieure, le cas échéant. 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 le document RFC7519.

Vidéo

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

Exemples

Valider un jeton JWT signé avec l'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 dont Edge a besoin pour décoder et évaluer le JWT, comme l'emplacement du jeton JWT (dans une variable de flux spécifiée dans l'élément "Source"), les champs algorithme de signature, où trouver la clé secrète (stockée dans une variable de flux Edge, qui pourrait provenant d'Edge KVM, 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.

Valider un jeton JWT signé avec l'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.

Définir les éléments clé

Les éléments que vous utilisez pour spécifier la clé utilisée pour valider le jeton JWT dépendent 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.

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._\-$ %. Cependant, l'interface utilisateur de gestion Edge applique des telles que la suppression automatique de 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.

ND Requis
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 permettant de signer le jeton. 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 Requis
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

<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 false
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 false
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 false
Présence Facultatif
Type Booléen
Valeurs valides true ou false

<Issuer>

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

La règle vérifie que l'émetteur du jeton JWT correspond à la chaîne spécifiée dans l'élément de configuration. C'est une revendication qui identifie l'émetteur du jeton JWT. Il s'agit d'un ensemble de revendications enregistrées et mentionnées dans le document RFC7519.

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.

<PublicKey/Certificate>

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

Spécifie le certificat signé utilisé pour valider la signature du jeton JWT. Utilisez l'attribut "ref" pour transmettre le certificat signé dans une variable de flux ou spécifiez directement le certificat encodé au format PEM. N'utilisez ce paramètre que lorsque l'algorithme est RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Par défaut N/A
Présence Pour valider un jeton JWT signé avec un algorithme RSA, vous devez utiliser les éléments "Certificate", "JWKS" ou "Value".
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

<PublicKey/JWKS>

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

or:

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

or:

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

Spécifie une valeur au format JWKS (RFC 7517) contenant un ensemble de clés publiques. À n'utiliser que lorsque l'algorithme est RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Si le jeton JWT entrant a un ID de clé présent dans l'ensemble de 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 extrayez la valeur à partir d'une URL publique, Edge met en cache le JWKS pendant une période de 300 secondes. Lorsque le cache expire, Edge récupère à nouveau les JWKS.

Par défaut N/A
Présence Pour valider un jeton JWT à l'aide d'un algorithme RSA, vous devez utiliser l'élément de certificat, JWKS ou Valeur.
Type Chaîne
Valeurs valides Une variable de flux, une valeur de chaîne ou une URL.

<PublicKey/Value>

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

Spécifie la clé publique ou le certificat public utilisé pour valider la signature du jeton JWT. Utilisez l'attribut "ref" pour transmettre la clé ou le certificat dans une variable de flux ou spécifiez directement la clé encodée au format PEM. À n'utiliser que lorsque l'algorithme est RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Par défaut N/A
Présence Pour valider un jeton JWT signé avec un algorithme RSA, vous devez utiliser les éléments "Certificate", "JWKS" ou "Value".
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

<SecretKey/Value>

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

Fournit la clé secrète utilisée pour vérifier ou signer les jetons avec un algorithme HMAC. Utilisation uniquement lorsque l'algorithme est HS256, HS384 ou HS512.

Par défaut N/A
Présence Obligatoire pour les algorithmes HMAC.
Type Chaîne
Valeurs valides

Pour encoding, les valeurs valides sont hex, base16, base64, ou base64url. Les valeurs d'encodage hex et base16 sont des synonymes.

Utiliser l'attribut ref pour transmettre la clé à une variable de flux.

Remarque : S'il s'agit d'une variable de flux, elle doit comporter le préfixe "private". Par exemple, private.mysecret.

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

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

<Subject>

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

La règle vérifie que le sujet du jeton JWT correspond à la chaîne spécifiée dans la configuration de la règle. Cette revendication identifie le sujet du jeton JWT ou donne une instruction le concernant. Il s'agit de l'ensemble standard de revendications mentionné dans le document RFC7519.

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

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Le "délai de grâce" pour les horaires. Par exemple, si l'intervalle de temps est configuré sur 60 secondes, un jeton JWT expiré sera considéré comme valide pendant les 60 secondes qui suivent la déclaration d'expiration. Les messages antérieurs à l'horaire sont évalués de la même manière. La valeur par défaut est de 0 seconde (aucun délai de grâce).

Par défaut 0 seconde (aucun délai de grâce)
Présence Facultatif
Type Chaîne
Valeurs valides Valeur ou référence à une variable de flux contenant la valeur. Les intervalles de temps peuvent être spécifiés comme suit :
  • s = secondes
  • m = minutes
  • h = heures
  • d = jours

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, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie 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 "Générer" ne correspond pas à celui attendu dans la règle "Vérifier". 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 revendication ou de non-concordance des revendications, ou si un en-tête ou un en-tête est manquant.
steps.jwt.InvalidCurve 401 La courbe spécifiée par la clé n'est pas valide pour l'algorithme à courbe elliptique.
steps.jwt.InvalidJsonFormat 401 JSON non valide trouvé dans l'en-tête ou la charge utile.
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 stratégie de validation utilise un JWKS comme source pour les clés publiques, mais le jeton JWT signé n'inclut pas de 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 de vérification 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 Solution
InvalidNameForAdditionalClaim Le déploiement échouera si la revendication utilisée dans l'élément enfant <Claim> de l'élément <AdditionalClaims> est 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 du 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 le type de revendication utilisé dans l'élément enfant <Claim> de l'élément <AdditionalClaims> n'est pas du 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 acceptée, le déploiement échouera.
MissingConfigurationElement Cette erreur se produit 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. Si elle est présente, elle doit être définie avec un nom de variable de flux Edge.
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 la RFC 7517, le déploiement échouera.
InvalidConfigurationForActionAndAlgorithm Si l'élément <PrivateKey> est utilisé avec des algorithmes de la famille HS ou que 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 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 "TokenExpired"
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 meilleur 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 "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>