Règle DecodeJWT

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

Consultez la documentation d'Apigee Edge.

icône de la règle

Quoi

Décode un jeton JWT sans valider la signature sur le jeton JWT. Le décodage est très utile lorsqu'il est utilisé avec la règle VerifyJWT, lorsque la valeur d'une revendication à partir du jeton JWT doit être connue avant de vérifier la signature du jeton JWT.

La règle de décodage JWT fonctionne quel que soit l'algorithme utilisé pour signer le jeton JWT. 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.

Vidéo

Regardez une courte vidéo pour apprendre à décoder un jeton JWT.

Exemple : Décoder un jeton JWT

La règle affichée ci-dessous décode un jeton JWT trouvé dans la variable de flux var.jwt. Cette variable doit être présente et contenir un jeton JWT viable (décodable). La règle peut obtenir le jeton JWT à partir de n'importe quelle variable de flux.

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

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.

Référence d'élément pour "Decode JWT"

La référence de la règle décrit les éléments et les attributs de la règle "Decode JWT".

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

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

Les attributs suivants sont communs à tous les éléments parents de la stratégie.

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

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

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

À utiliser, en plus de l'attribut, pour appliquer un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur d'Apigee en utilisant un nom différent, en langage naturel.

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

<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 à décoder.

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

Variables de flux

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

jwt.{policy_name}.{variable_name}

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

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

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

Informations de référence sur les erreurs

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 Cause Corriger
steps.jwt.FailedToDecode 401 Se produit lorsque la règle ne parvient pas à décoder le jeton JWT. Le jeton JWT peut être incorrect, non valide ou indécodable.
steps.jwt.FailedToResolveVariable 401 Cette erreur se produit si la variable de flux spécifiée dans l'élément <Source> de la règle n'existe pas.
steps.jwt.InvalidToken 401 Se produit lorsque la variable de flux spécifiée dans l'élément <Source> de la règle est hors champ d'application ou ne peut être résolue.

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
InvalidEmptyElement Se produit lorsque la variable de flux contenant le jeton JWT à décoder n'est pas spécifiée dans l'élément <Source> de la règle.

Variables de panne

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

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>