<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
- Valider un jeton JWT signé avec l'algorithme RS256
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 |
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 |
faux | Facultatif |
activé | Définissez la valeur sur true pour appliquer la stratégie.Définissez la valeur sur |
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 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, |
<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 :
|
Flow variables
Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:
jwt.{policy_name}.{variable_name}
For example, if the policy name is jwt-parse-token
, then the policy will store
the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub
.
(For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject
)
Variable name | Description |
---|---|
claim.audience |
The JWT audience claim. This value may be a string, or an array of strings. |
claim.expiry |
The expiration date/time, expressed in milliseconds since epoch. |
claim.issuedat |
The Date the token was issued, expressed in milliseconds since epoch. |
claim.issuer |
The JWT issuer claim. |
claim.notbefore |
If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch. |
claim.subject |
The JWT subject claim. |
claim.name |
The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload. |
decoded.claim.name |
The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for
every claim in the payload. For example, you can use decoded.claim.iat to
retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you
can also use the claim.name flow variables, this is the
recommended variable to use to access a claim. |
decoded.header.name |
The JSON-parsable value of a header in the payload. One variable is set for
every header in the payload. While you can also use the header.name flow variables,
this is the recommended variable to use to access a header. |
expiry_formatted |
The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more. |
header.kid |
The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more. |
header.type |
Will be set to JWT . |
header.name |
The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT. |
header-json |
The header in JSON format. |
is_expired |
true or false |
payload-claim-names |
An array of claims supported by the JWT. |
payload-json |
The payload in JSON format.
|
seconds_remaining |
The number of seconds before the token will expire. If the token is expired, this number will be negative. |
time_remaining_formatted |
The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926 |
valid |
In the case of VerifyJWT, this variable will be true when the signature is verified, and
the current time is before the token expiry, and after the token notBefore value, if they
are present. Otherwise false.
In the case of DecodeJWT, this variable is not set. |
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 Edge 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.InvalidCurve |
401 | The curve specified by the key is not valid for the Elliptic Curve algorithm. |
steps.jwt.InvalidJsonFormat |
401 | Invalid JSON found in the header or payload. |
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 .
|
build |
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.
|
build |
MissingNameForAdditionalClaim |
If the name of the claim is not specified in the child element <Claim>
of the <AdditionalClaims> element, the deployment will fail.
|
build |
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 .
|
build |
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.
|
build |
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 .
|
build |
InvalidValueForElement |
If the value specified in the <Algorithm> element is not a supported value,
the deployment will fail.
|
build |
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.
|
build |
InvalidKeyConfiguration |
If the child element <Value> is not defined in the <PrivateKey>
or <SecretKey> elements, the deployment will fail.
|
build |
EmptyElementForKeyConfiguration |
If the ref attribute of the child element <Value> of the <PrivateKey>
or <SecretKey> elements is empty or unspecified, the deployment will fail.
|
build |
InvalidConfigurationForVerify |
This error occurs if the <Id> element is defined within the
<SecretKey> element.
|
build |
InvalidEmptyElement |
This error occurs if the <Source> element of the Verify JWT policy
is empty. If present, it must be defined with an Edge flow variable name.
|
build |
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.
|
build |
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.
|
build |
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "TokenExpired" |
JWT.failed |
All JWT policies set the same variable in the case of a failure. | JWT.failed = true |
Example error response
For error handling, the best practice is to trap the errorcode
part of the error
response. Do not rely on the text in the faultstring
, because it could change.
Example fault rule
<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>