Règle DecodeJWT
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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

Consultez la documentation d'Apigee Edge.

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.

Remarque : Par défaut, le jeton JWT est récupéré à partir de la variable request.header.authorization. Dans ce cas, Apigee recherche le jeton JWT dans l'en-tête "Authorization" de la requête. 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 jeton JWT dans l'en-tête "Authorization" de la manière suivante :

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).
Presence	Facultatif
Type	Chaîne
Valeurs valides	Nom de variable de flux Apigee

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 Apigee 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	Cause
`steps.jwt.FailedToDecode`	`401`	Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
`steps.jwt.FailedToResolveVariable`	`401`	Occurs when the flow variable specified in the `<Source>` element of the policy does not exist.
`steps.jwt.InvalidToken`	`401`	Occurs when the flow variable specified in the `<Source>` element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidEmptyElement`	Occurs when the flow variable containing the JWT to be decoded is not specified in the `<Source>` element of the policy.

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>