Cette page a été traduite par l'API Cloud Translation.

Règle DecodeJWT

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

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.

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	Présence
name	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 restrictions supplémentaires, telles que la suppression automatique des caractères qui ne sont pas alphanumériques. Vous pouvez également utiliser l'élément `<displayname></displayname>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
continueOnError	Définissez sur `false` pour afficher une erreur en cas d'échec d'une stratégie. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur `true` pour que l'exécution du flux se poursuive même après l'échec d'une règle.	false	Facultatif
activé	Définissez sur `true` pour appliquer la règle. Définissez la valeur sur `false` pour "désactiver" la stratégie. La stratégie ne sera pas appliquée même si elle reste associée à un flux.	true	Facultatif
async	Cet attribut est obsolète.	false	Obsolète

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Utilisez-le, en plus de l'attribut "name", pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

Par défaut	Si vous omettez cet élément, la valeur de l'attribut de nom de la stratégie est utilisée.
Présence	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.

Remarque : Par défaut, le jeton JWT est récupéré à partir de la variable request.header.authorization. Dans ce cas, Edge recherche le JWT dans l'en-tête de requête d'autorisation. Si vous transmettez le jeton JWT dans l'en-tête "Authorization", vous n'avez pas besoin d'inclure l'élément source dans la règle. Cependant, vous devez inclure Bearer dans l'en-tête d'authentification. Par exemple, vous devez transmettre le JWT dans l'en-tête d'autorisation comme suit :

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

Vous pouvez configurer une règle pour extraire le jeton JWT à partir d'une variable de paramètre de formulaire, de requête ou de toute autre variable. Si la variable n'existe pas ou si la règle ne parvient pas à trouver le jeton JWT, celle-ci renvoie une erreur.

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	Un nom de variable de flux Edge

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	Cause
`steps.jwt.FailedToDecode`	401	Se produit lorsque la stratégie ne parvient pas à décoder le jeton JWT. Le jeton JWT peut être incorrect, non valide ou non dé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	Où :	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>