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

Règle DecodeJWS

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

Quoi

Décode l'en-tête JWS sans valider la signature sur le jeton JWS, et écrit chaque en-tête dans une variable de flux. Cette règle est particulièrement utile lorsqu'elle est utilisée conjointement avec la règle VerifyJWS, lorsque la valeur d'un en-tête dans le jeton JWS doit être connue avant de valider la signature du jeton JWS.

Un JWS peut avoir une charge utile attachée, comme suit :

header.payload.signature

Ou un JWS peut omettre la charge utile, appelée charge utile detached, et se présenter sous la forme suivante :

header..signature

La règle DecodeJWS fonctionne avec les deux formes, car elle ne décode que la partie en-tête du JWS. La règle DecodeJWS fonctionne également, quel que soit l'algorithme utilisé pour signer le JWS.

Pour obtenir une présentation détaillée et une vue d'ensemble du format d'un JWS, consultez la page Présentation des règles JWS et JWT.

Vidéo

Regardez une courte vidéo pour apprendre à décoder un jeton JWT. Bien que cette vidéo soit spécifique à la génération d'un jeton JWT, de nombreux concepts sont les mêmes pour JWS.

Exemple : décoder un JWS

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

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

Pour chaque en-tête de la partie en-tête du JWS, la règle définit une variable de flux nommée :

jws.policy-name.header.header-name

Si le jeton JWS est associé à une charge utile, il définit la variable de flux jws.policy-name.header.payload sur la charge utile. Pour une charge utile dissociée, payload est vide. Pour obtenir la liste complète des variables définies par cette règle, consultez la section Variables de flux.

Référence d'élément pour le décodage de JWS

La référence de règle décrit les éléments et les attributs de la règle de décodage de JWS.

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

<DecodeJWS name="JWS" 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>JWS-variable</Source>

Le cas échéant, spécifie la variable de flux dans laquelle la règle s'attend à trouver le jeton JWS à décoder.

Remarque : Par défaut, le jeton JWS est récupéré à partir de la variable request.header.authorization. Dans ce cas, Edge recherche le JWS dans l'en-tête de requête d'autorisation. Si vous transmettez le jeton JWS 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 JWS dans l'en-tête d'autorisation comme suit :

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

Vous pouvez configurer une règle pour extraire le jeton JWS à 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 JWS, 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 VerifyJWS et DecodeJWS définissent les variables de contexte conformément à ce modèle :

jws.{policy_name}.{variable_name}

Par exemple, si le nom de la règle est verify-jws, la règle stocke l'algorithme spécifié dans le JWS dans cette variable de contexte : jws.verify-jws.header.algorithm

Nom de la variable	Description
`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.
`header.algorithm`	Algorithme de signature utilisé sur le JWS. 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 JWS a été généré. Pour vérifier un JWS, consultez également la section "Utiliser un jeu de clés Web JSON (JWKS)" sur la page Présentation des règles JWT et JWS. Consultez la section Paramètre d'en-tête (ID de clé) pour en savoir plus.
`header.type`	Valeur du type d'en-tête. Pour en savoir plus, consultez la section Paramètre d'en-tête (type).
`header.name`	Valeur de l'en-tête nommé (standard ou supplémentaire). L'une de ces valeurs sera définie pour chaque en-tête supplémentaire dans la partie en-tête du JWS.
`header-json`	En-tête au format JSON.
`payload`	Charge utile JWS si une charge utile est associée au JWS. Pour une charge utile dissociée, cette variable est vide.
`valid`	Dans le cas de VerifyJWS, cette variable est "true" lorsque la signature est vérifiée, et que l'heure actuelle est antérieure à l'expiration du jeton et après la valeur notBefore, si elles sont présentes. Sinon, la valeur est false. Dans le cas de DecodeJWS, 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	Se produit quand
`steps.jws.FailedToDecode`	401	La règle n'a pas pu décoder le jeton JWS. Le jeton JWS est peut-être corrompu.
`steps.jws.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.jws.InvalidClaim`	401	en cas de revendication ou de non-concordance des revendications, ou si un en-tête ou un en-tête est manquant.
`steps.jws.InvalidJsonFormat`	401	JSON non valide trouvé dans l'en-tête JWS.
`steps.jws.InvalidJws`	401	Cette erreur se produit en cas d'échec de la validation de la signature du jeton JWS.
`steps.jws.InvalidPayload`	401	La charge utile JWS n'est pas valide.
`steps.jws.InvalidSignature`	401	`<DetachedContent>` est omis et le jeton JWS possède une charge utile de contenu dissociée.
`steps.jws.MissingPayload`	401	La charge utile JWS est manquante.
`steps.jws.NoAlgorithmFoundInHeader`	401	Cette erreur produit lorsque le jeton JWS omet l'en-tête de l'algorithme.
`steps.jws.UnknownException`	401	Une exception inconnue s'est produite.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur Se produit quand

InvalidAlgorithm Les seules valeurs valides sont : RRS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

Nom de l'erreur	Se produit quand
`InvalidAlgorithm`	Les seules valeurs valides sont : RRS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.
`EmptyElementForKeyConfiguration` `FailedToResolveVariable` `InvalidConfigurationForActionAndAlgorithmFamily` `InvalidConfigurationForVerify` `InvalidEmptyElement` `InvalidFamiliesForAlgorithm` `InvalidKeyConfiguration` `InvalidNameForAdditionalClaim` `InvalidNameForAdditionalHeader` `InvalidPublicKeyId` `InvalidPublicKeyValue` `InvalidSecretInConfig` `InvalidTypeForAdditionalClaim` `InvalidTypeForAdditionalHeader` `InvalidValueForElement` `InvalidValueOfArrayAttribute` `InvalidVariableNameForSecret` `MissingConfigurationElement` `MissingElementForKeyConfiguration` `MissingNameForAdditionalClaim` `MissingNameForAdditionalHeader`	Autres erreurs de déploiement possibles.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Autres erreurs de déploiement possibles.

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"`
`JWS.failed`	Toutes les règles JWS définissent la même variable en cas d'échec.	`jws.JWS-Policy.failed = true`

Exemple de réponse d'erreur

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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>