Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'
Apigee Edge.
La règle DecodeJWS 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.
Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.
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._\-$ %. 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 |
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 |
faux | Facultatif |
| activé | Définissez la valeur sur true pour appliquer la stratégie.Définissez la valeur sur |
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.
| 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 | Nom de variable de flux Apigee |
流变量
成功后,验证 JWS 和解码 JWS 政策将根据此模式设置上下文变量:
jws.{policy_name}.{variable_name}
例如,如果政策名称为 verify-jws,则该政策会将 JWS 中指定的算法存储在此上下文变量中:jws.verify-jws.header.algorithm
| 变量名称 | 说明 |
|---|---|
decoded.header.name |
载荷中标头的 JSON 可解析值。为载荷中的每个标头设置一个变量。虽然您还可以使用 header.name 流变量,但建议使用此变量来访问标头。 |
header.algorithm |
JWS 中使用的签名算法。例如 RS256、HS384 等。如需了解详情,请参阅(算法)标头参数。 |
header.kid |
生成 JWS 时添加的密钥 ID。另请参阅 JWT 和 JWS 政策概览中的“使用 JSON 网络密钥集 (JWKS)”来验证 JWS。如需了解详情,请参阅(密钥 ID)标头参数。 |
header.type |
标头类型值。如需了解详情,请参阅(类型)标头参数。 |
header.name |
已命名标头的值(标准或附加)。将为 JWS 标头部分中的每个附加标头设置其中一个。 |
header-json |
JSON 格式的标头。 |
payload |
如果 JWS 具有附加的载荷,则为 JWS 载荷。对于分离的载荷,此变量为空。 |
valid |
对于 VerifyJWS,在验证签名时,此变量为 true,而且当前时间在令牌有效期之前且在令牌 notBefore 值之后(如果两者存在)。否则为 false。 对于 DecodeJWS,无需设置此变量。 |
Informations de référence sur les erreurs
Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle 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 problème de revendication ou de revendication manquante, de problème d'en-tête ou d'en-tête 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 : RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512. |
|
|
Autres erreurs de déploiement possibles. |
故障变量
发生运行时错误时,系统会设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。
| 变量 | 其中 | 示例 |
|---|---|---|
fault.name="fault_name" |
fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 | fault.name Matches "TokenExpired" |
JWS.failed |
所有 JWT 政策都将在发生故障时设置同一变量。 | jws.JWS-Policy.failed = true |
错误响应示例
处理错误时,最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本,因为它可能会发生变化。
故障规则示例
<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>