DecodeJWT 政策

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

内容

解码 JWT，而不验证 JWT 的签名。与 VerifyJWT 政策搭配使用时，当必须在验证 JWT 的签名之前知道来自 JWT 的声明的值时，这最为有用。

无论用于签署 JWT 的算法是哪个，JWT 解码政策都有效。如需查看详细介绍，请参阅 JWS 和 JWT 政策概览。

视频

观看视频短片，了解如何解码 JWT。

示例：解码 JWT

下面所示的政策会对在流变量 var.jwt 中找到的 JWT 进行解码。此变量必须存在，并且包含可行（可声明）JWT。该政策可以从任何流变量获取 JWT。

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

该政策会将其输出写入上下文变量，以便 API 代理中的后续政策或条件检查这些值。如需查看此政策设置的变量列表，请参阅流变量。

解码 JWT 的元素参考

政策参考介绍了“解码 JWT 政策”的元素和属性。

适用于顶级元素的属性

<DecodeJWT name="JWT" 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>jwt-variable</Source>

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

默认 request.header.authorization（请参阅上述“注意”部分，了解有关默认值的重要信息。）
状态 可选
类型 字符串
有效值 Edge 流变量名称

Flow variables

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

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
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.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
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 JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, 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 DecodeJWT, this variable is not set.

错误参考信息

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 Cause Fix
steps.jwt.FailedToDecode 401 Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
steps.jwt.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jwt.InvalidToken 401 Occurs when the flow variable specified in the <Source> element of the policy is out of scope or can't be resolved.

Deployment errors

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

Error name Cause Fix
InvalidEmptyElement Occurs when the flow variable containing the JWT to be decoded is not specified in the <Source> element of the policy.

故障变量

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

变量 地点 示例
fault.name="fault_name" fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "TokenExpired"
JWT.failed 所有 JWT 政策都将在发生故障时设置同一变量。 JWT.failed = true

错误响应示例

JWT 政策故障代码

处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

故障规则示例

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>