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

Règle DecodeJWS

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur 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 dissociée, 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
nom	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 telles que la suppression automatique de 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.	ND	Requis
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.	faux	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.	vrai	Facultatif
async	Cet attribut est obsolète.	faux	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 le "Request Authorization". 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 pouvez transmettre le JWS dans d'autorisation comme ceci:

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

Flow variables

Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

Variable name	Description
`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.
`header.algorithm`	The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
`header.kid`	The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more.
`header.type`	The header type value. See (Type) Header Parameter for more.
`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 JWS.
`header-json`	The header in JSON format.
`payload`	The JWS payload if the JWS has an attached payload. For a detached payload, this variable is empty.
`valid`	In the case of VerifyJWS, 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 DecodeJWS, 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 Edge 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	Occurs when
`steps.jws.FailedToDecode`	401	The policy was unable to decode the JWS. The JWS is possibly corrupted.
`steps.jws.FailedToResolveVariable`	401	Occurs when the flow variable specified in the `<Source>` element of the policy does not exist.
`steps.jws.InvalidClaim`	401	For a missing claim or claim mismatch, or a missing header or header mismatch.
`steps.jws.InvalidJsonFormat`	401	Invalid JSON found in the JWS header.
`steps.jws.InvalidJws`	401	This error occurs when the JWS signature verification fails.
`steps.jws.InvalidPayload`	401	The JWS payload is invalid.
`steps.jws.InvalidSignature`	401	`<DetachedContent>` is omitted and the JWS has a detached content payload.
`steps.jws.MissingPayload`	401	The JWS payload is missing.
`steps.jws.NoAlgorithmFoundInHeader`	401	Occurs when the JWS omits the algorithm header.
`steps.jws.UnknownException`	401	An unknown exception occurred.

Deployment errors

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

Error name Occurs when

InvalidAlgorithm The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

Error name	Occurs when
`InvalidAlgorithm`	The only valid values are: RS256, 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`	Other possible deployment errors.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Other possible deployment errors.

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 "TokenExpired"`
`JWS.failed`	All JWS policies set the same variable in the case of a failure.	`jws.JWS-Policy.failed = true`

Example error response

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