DecodeJWS 政策

本页面适用于 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 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

视频

注意：以下视频显示了 Apigee 界面中的经典版代理编辑器。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">

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

属性	说明	默认	状态
name	政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。但是，Apigee 界面会实施其他限制，例如自动移除非字母数字字符。 （可选）使用 <displayname></displayname> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必填
continueOnError	设置为 false 可在政策失败时返回错误。对于大多数政策来说，这一行为符合预期。 设置为 true，即使在政策失败后，仍可以继续实施流执行。	false	可选
已启用	设置为 true 可实施政策。 设置为 false 可“关闭”政策。即使政策仍附加到某个流，也不会实施该政策。	true	可选
async	此属性已弃用。	false	已弃用

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>JWS-variable</Source>

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

注意：默认情况下，JWS 从变量 request.header.authorization 检索。在这种情况下，Apigee 会在请求的 Authorization 标头中查找 JWS。如果在 Authorization 标头中传递 JWS，则无需将 Source 元素包括在政策中；但是，必须包括将 Bearer 包括在 auth 标头中。例如，您可以在 Authorization 标头中传递 JWS，如下所示：

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

您可以对政策进行配置，以从表单或查询参数变量或任何其他变量中检索 JWS。如果变量不存在，或者政策找不到 JWS，则政策会返回错误。

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

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.
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.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>