DecodeJWS 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

对 JWS 标头进行解码，而不验证 JWS 的签名，并将每个标头写入流变量。与 VerifyJWS 政策搭配使用时，当必须在验证 JWS 签名之前知道 JWS 中的标头值时，此政策最为有用。

JWS 可以附加载荷，格式如下：

header.payload.signature

或者，JWS 可以省略载荷（称为分离载荷），格式如下：

header..signature

DecodeJWS 政策适用于这两种格式，因为它仅解码 JWS 的标头部分。无论用于签署 JWS 的算法是哪个，DecodeJWS 政策也可正常工作。

如需详细了解 JWS 和 JWS 的格式，请参阅 JWS 和 JWT 政策概览。

视频

观看视频短片，了解如何解码 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">

以下属性是所有政策的父级元素都具有的属性。

属性 说明 默认 状态
name 政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。不过，Edge 管理界面会强制实施 限制，例如自动移除非字母数字字符。

（可选）使用 <displayname></displayname> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必填
continueOnError 设置为 false 可在政策失败时返回错误。对于大多数政策来说，这一行为符合预期。

设置为 true，即使在政策失败后，仍可以继续实施流执行。

 false 可选
已启用 设置为 true 可实施政策。

设置为 false 可“关闭”政策。即使政策仍附加到某个流，也不会实施该政策。

 true 可选
异步 此属性已弃用。 false 已弃用

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了用于名称属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

默认 如果省略此元素，则会使用政策的名称属性的值。
状态 可选
类型 字符串

<Source>

<Source>JWS-variable</Source>

如果存在，请指定政策在其中查找要解码的 JWS 的流变量。

默认 request.header.authorization（请参阅上述“注意”部分，了解有关默认值的重要信息。）
状态 可选
类型 字符串
有效值 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.

错误参考信息

本部分介绍了在此政策触发错误时返回的错误代码和错误消息，以及 Edge 设置的故障变量。 在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 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。

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 其他可能的部署错误。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量 其中 示例
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>