DecodeJWT 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

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

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

此政策为标准政策，可部署到任何环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

视频

注意：以下视频显示了 Apigee 界面中的经典版代理编辑器。Apigee 推出了新版代理编辑器，其设计与视频中显示的经典版不同。

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

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

注意：默认情况下，系统会从变量 request.header.authorization 检索 JWT。在这种情况下，Apigee 会在请求的 Authorization 标头中查找 JWT。如果您在 Authorization 标头中传递 JWT，则无需在政策中添加 Source 元素；但是，您必须在身份验证标头中添加不记名令牌。例如，您可以在 Authorization 标头中传递 JWT，如下所示：

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

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

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

流变量

验证成功后，验证 JWT 和解码 JWT 政策将根据以下模式设置上下文变量：

jwt.{policy_name}.{variable_name}

例如，如果政策名称为 jwt-parse-token，则该政策会将 JWT 中指定的主题存储在名为 jwt.jwt-parse-token.decoded.claim.sub 的上下文变量中。（为实现向后兼容性，jwt.jwt-parse-token.claim.subject 中也提供此主题）

变量名称	说明
claim.audience	JWT 目标对象声明。此值可以是字符串，也可以是字符串数组。
claim.expiry	到期日期/时间（自新纪元开始算起，以毫秒为单位）。
claim.issuedat	令牌的签发日期（自新纪元开始算起，以毫秒为单位）。
claim.issuer	JWT 签发者声明。
claim.notbefore	如果 JWT 包含 nbf 声明，则此变量将包含该值（自新纪元开始算起，以毫秒为单位）。
claim.subject	JWT 主题声明。
claim.name	载荷中已命名声明（标准或附加）的值。为载荷中的每个声明设置其中一个值。
decoded.claim.name	载荷中已命名声明（标准或附加）的 JSON 可解析值。为载荷中的每个声明设置一个变量。例如，您可以使用 decoded.claim.iat 检索 JWT 的颁发时间（自新纪元开始算起，以秒为单位）。虽然您还可以使用 claim.name 流变量，但这也是用来访问声明的推荐变量。
decoded.header.name	载荷中标头的 JSON 可解析值。为载荷中的每个标头设置一个变量。虽然您还可以使用 header.name 流变量，但建议使用此变量来访问标头。
expiry_formatted	到期日期/时间，以人类可读的字符串的形式表示。示例：2017-09-28T21:30:45.000+0000
header.algorithm	JWT 中使用的签名算法。例如 RS256、HS384 等。如需了解详情，请参阅（算法）标头参数。
header.kid	密钥 ID（如果生成 JWT 时添加了的话）。另请参阅 JWT 政策概览中的“使用 JSON 网络密钥集 (JWKS)”来验证 JWT。如需了解详情，请参阅（密钥 ID）标头参数。
header.type	将设为 JWT。
header.name	已命名标头的值（标准或附加）。将为 JWT 的标头部分中的每个附加标头设置其中一个值。
header-json	JSON 格式的标头。
is_expired	true 或 false
payload-claim-names	JWT 支持的一组声明。
payload-json	JSON 格式的载荷。
seconds_remaining	令牌过期前的秒数。如果令牌过期，此数字将为负数。
time_remaining_formatted	令牌过期前的剩余时间（以人类可读的字符串的形式表示）。示例：00:59:59.926
valid	对于 VerifyJWT，在验证签名时，此变量为 true，而且当前时间在令牌有效期之前且在令牌 notBefore 值之后（如果两者存在）。否则为 false。 对于 DecodeJWT，无需设置此变量。

错误参考信息

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

运行时错误

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

故障代码	HTTP 状态	原因	修复
steps.jwt.FailedToDecode	401	在政策无法解码 JWT 时发生。JWT 格式可能格式不正确、无效或不可解码。
steps.jwt.FailedToResolveVariable	401	在政策的 <Source> 元素中指定的流变量不存在时发生。
steps.jwt.InvalidToken	401	如果政策的 <Source> 元素中指定的流变量超出范围或无法解析，则会发生此错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称	原因	修复
InvalidEmptyElement	在政策的 <Source> 元素中未指定包含要解码的 JWT 的流变量时发生。

故障变量

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

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

错误响应示例

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

故障规则示例

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