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

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

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 "InvalidToken"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

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 "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>