本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
内容
对 JWS 标头进行解码，而不验证 JWS 的签名，并将每个标头写入流变量。与 VerifyJWS 政策搭配使用时，当必须在验证 JWS 签名之前知道 JWS 中的标头值时，此政策最为有用。
JWS 可以附加载荷，格式如下：
header.payload.signature
或者，JWS 可以省略载荷（称为分离载荷），格式如下：
header..signature
DecodeJWS 政策适用于这两种格式，因为它仅解码 JWS 的标头部分。无论用于签署 JWS 的算法是哪个，DecodeJWS 政策也可正常工作。
如需详细了解 JWS 和 JWS 的格式，请参阅 JWS 和 JWT 政策概览。
此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。
视频
观看视频短片，了解如何解码 JWT。虽然此视频专用于 JWT，但其中的许多概念同样适用于 JWS。
示例：解码 JWS
下面所示的政策将对在流变量 var.JWS 中找到的 JWS 进行解码。此变量必须存在，并且包含可行（可声明）JWS。该政策可以从任何流变量获取 JWS。
<DecodeJWS name="JWS-Decode-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Source>var.JWS</Source> </DecodeJWS>
对于 JWS 的标头部分中的每个标头，该策略将设置一个如下名称的流变量：
jws.policy-name.header.header-name
如果 JWS 附加了载荷，则它将 jws.policy-name.header.payload 流变量设置为载荷。对于分离载荷，payload 为空。如需查看此政策设置的变量的完整列表，请参阅流变量。
解码 JWS 的元素参考
政策参考介绍了“解码 JWS 政策”的元素和属性。
适用于顶级元素的属性
<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">
以下属性是所有政策的父级元素都具有的属性。
| 属性 | 说明 | 默认 | Presence |
|---|---|---|---|
| name |
政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。但是，Apigee 界面会实施其他限制，例如自动移除非字母数字字符。（可选）使用 |
不适用 | 必需 |
| continueOnError |
设置为 false 可在政策失败时返回错误。对于大多数政策来说，这一行为符合预期。设置为 |
false | 可选 |
| 已启用 | 设置为 true 可实施政策。设置为 |
true | 可选 |
| async | 此属性已弃用。 | false | 已弃用 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了用于名称属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
| 默认 | 如果省略此元素，则会使用政策的名称属性的值。 |
| Presence | 可选 |
| 类型 | 字符串 |
<Source>
<Source>JWS-variable</Source>
如果存在，请指定政策在其中查找要解码的 JWS 的流变量。
| 默认 | request.header.authorization（请参阅上述“注意”部分，了解有关默认值的重要信息。） |
| Presence | 可选 |
| 类型 | 字符串 |
| 有效值 | 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，无需设置此变量。 |
错误参考信息
本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 发生的条件 |
|---|---|---|
steps.jws.FailedToDecode |
401 |
该政策无法解码 JWS。JWS 可能已损坏。 |
steps.jws.FailedToResolveVariable |
401 |
在政策的 <Source> 元素中指定的流变量不存在时发生。 |
steps.jws.InvalidClaim |
401 |
用于缺失声明或声明不匹配，或者缺少标题或标头不匹配的情况。 |
steps.jws.InvalidJsonFormat |
401 |
可在 JWS 标头中找到无效的 JSON。 |
steps.jws.InvalidJws |
401 |
当 JWS 签名验证失败时，会发生此错误。 |
steps.jws.InvalidPayload |
401 |
JWS 负载无效。 |
steps.jws.InvalidSignature |
401 |
省略 <DetachedContent> 并且 JWS 具有分离的内容负载。 |
steps.jws.MissingPayload |
401 |
JWS 负载缺失。 |
steps.jws.NoAlgorithmFoundInHeader |
401 |
在 JWS 省略算法标头时发生。 |
steps.jws.UnknownException |
401 |
发生未知异常。 |
部署错误
在您部署包含此政策的代理时，可能会发生这些错误。
| 错误名称 | 发生的条件 |
|---|---|
InvalidAlgorithm |
唯一的有效值为：RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512。 |
|
|
其他可能的部署错误。 |
故障变量
发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。
| 变量 | 地点 | 示例 |
|---|---|---|
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>