验证 JWT 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

是什么

验证签名 JWT，或者解密并验证从客户端或其他系统收到的加密 JWT。此政策还会将声明提取到上下文变量中，这样后续政策或条件就可以检查这些值，以做出授权或路由决策。如需查看详细介绍，请参阅 JWS 和 JWT 政策概览。

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

此政策在执行时，如果是签名 JWT，Apigee 会使用提供的验证密钥验证 JWT 的签名。如果是加密 JWT，Apigee 会使用解密密钥解密 JWT。对于上述任何一种情况，Apigee 随后都会根据到期时间和“不早于”时间（如有）验证 JWT 是否有效。（可选）该政策还可以验证 JWT 中特定声明的值，例如主题、颁发者、受众群体或附加声明的值。

如果 JWT 经过验证且有效，则 JWT 中包含的所有声明将被提取到上下文变量中，以供后续政策或条件使用，并且系统会允许继续执行请求。如果 JWT 签名无法验证，或者 JWT 因某个时间戳而无效，则系统会停止所有处理并在响应中返回错误。

如需了解 JWT 各部分及其加密和签名的方式，请参阅 RFC7519。

方式

政策是验证签名 JWT 还是加密 JWT 取决于您是使用哪种元素来指定用于验证 JWT 的算法：

如果您使用 <Algorithm> 元素，则政策会验证签名 JWT。
如果您使用 <Algorithms> 元素，则政策会验证加密 JWT。

视频

观看视频短片，了解如何验证 JWT 签名。

验证签名 JWT

本部分介绍如何验证签名 JWT。对于签名 JWT，请使用 <Algorithm> 元素指定用于为密钥签名的算法。

签名 JWT 的示例

以下示例说明了如何验证签名 JWT。

HS256 算法

此示例政策验证了采用 HS256 加密算法（即使用 SHA-256 校验的 HMAC ）进行签名的 JWT。系统会使用名为 jwt 的表单参数在代理请求中传递 JWT。该密钥包含在名为 private.secretkey 的变量中。请观看上方视频，了解完整示例（包括如何向政策发出请求）。

政策配置包括 Apigee 解码和评估 JWT 需要的信息，例如在哪里查看 JWT（在源元素中指定的流变量中）、所需的签名算法、在哪里查看密钥（例如，存储在可从 Apigee KVM 检索的 Apigee 流程变量中），以及一组必要的声明及其值。

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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

RS256 算法

注意：使用同一示例验证采用 PS256 或 ES256 算法的 JWT。只需将 <Algorithm>RS256</Algorithm> 的值更改为 PS256 或 ES256 即可。对于 ES256，您还必须指定与算法兼容的密钥。如需详细了解密钥要求，请参阅签名加密算法简介。

此示例政策验证了采用 RS256 算法进行签名的 JWT。要进行验证，您需要提供公钥。系统会使用名为 jwt 的表单参数在代理请求中传递 JWT。公钥包含在名为 public.publickey 的变量中。请观看上方视频，了解完整示例（包括如何向政策发出请求）。

请参阅“元素参考”，详细了解此示例政策中每个元素的要求和方案。

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

对于以上配置，如果 JWT 带有以下标头…

{
  "typ" : "JWT",
  "alg" : "RS256"
}

和以下载荷…

{
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

那么该 JWT 将被视为有效（前提是可以使用提供的公钥验证签名）。

如果 JWT 带有同一标头但载荷为以下内容…

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

那么该 JWT 将被视为无效，即使可以验证签名，结果也如此，因为 JWT 中包含的“sub”声明与政策配置中指定的“Subject”元素的要求值不一致。

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

上述示例使用 <Algorithm> 元素，因此它们会验证签名 JWT。<PrivateKey> 元素指定用于为 JWT 签名的密钥。此外，还有一些其他的密钥元素。使用哪种密钥元素取决于通过 <Algorithm> 的值指定的算法，如下一部分所述。

设置密钥元素以验证签名 JWT

以下元素指定用于验证签名 JWT 的密钥：

<SecretKey>
<PublicKey>

使用哪种元素取决于所选算法，如下表所示：

算法	密钥元素
HS*	<SecretKey encoding="base16\|hex\|base64\|base64url"> <Value ref="private.secretkey"/> </SecretKey>
RS、ES、PS*	<PublicKey> <Value ref="rsa_public_key_or_value"/> </PublicKey> 或者： <PublicKey> <Certificate ref="signed_cert_val_ref"/> </PublicKey> 或者： <PublicKey> <JWKS ref="jwks_val_or_ref"/> </PublicKey>
^*如需详细了解密钥要求，请参阅签名加密算法简介。

算法

密钥元素

HS*

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

RS*、ES*、PS*

<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

或者：

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

或者：

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>

^*如需详细了解密钥要求，请参阅签名加密算法简介。

验证加密 JWT

本部分介绍如何验证加密 JWT。对于加密 JWT，请使用 <Algorithms> 元素指定用于为密钥和内容签名的算法。

加密 JWT 的示例

以下示例展示了如何验证加密 JWT（即 <Type> 设置为 Encrypted），其中：

密钥使用 RSA-OAEP-256 算法进行加密。
内容使用 A128GCM 算法进行加密。

<VerifyJWT name="vjwt-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <Type>Encrypted</Type> 
  <PrivateKey>
    <Value ref="private.rsa_privatekey"/>
  </PrivateKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <TimeAllowance>30s</TimeAllowance>
  <Source>input_var</Source>
</VerifyJWT>

上面的示例使用 <Algorithms> 元素，因此它会验证加密 JWT。<PrivateKey> 元素指定用于解密 JWT 的密钥。此外，还有一些其他的密钥元素。使用哪种密钥元素取决于通过 <Algorithms> 的值指定的算法，如下一部分所述。

设置密钥元素以验证加密 JWT

以下元素指定用于验证加密 JWT 的密钥：

<PrivateKey>
<SecretKey>
<PasswordKey>
<DirectKey>

使用哪种元素取决于所选密钥加密算法，如下表所示：

算法	密钥元素
RSA-OAEP-256	<PrivateKey> <Value ref="private.rsa_privatekey"/> </PrivateKey> 注意：您指定的变量必须解析为 PEM 编码格式的 RSA 私钥。
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PrivateKey> <Value ref="private.ec_privatekey"/> </PrivateKey> 注意：您指定的变量必须解析为 PEM 编码格式的椭圆曲线私钥。
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey encoding="base16\|hex\|base64\|base64url"> <Value ref="private.flow-variable-name-here"/> </SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey> <Value ref="private.password-key"/> <SaltLength> <PBKDF2Iterations> </PasswordKey>
dir	<DirectKey> <Value encoding="base16\|hex\|base64\|base64url" ref="private.directkey"/> </DirectKey>

如需详细了解密钥要求，请参阅签名加密算法简介。

元素参考

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

注意：配置因您使用的加密算法而有些许差异。如需查看演示特定用例配置的示例，请参阅示例。

适用于顶级元素的属性

<VerifyJWT name="JWT" 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>

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

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

<Algorithm>

<Algorithm>HS256</Algorithm>

指定用于验证令牌的加密算法。使用 <Algorithm> 元素验证签名 JWT。

RS*/PS*/ES* 算法使用公钥/密钥对，而 HS* 算法使用共享密钥。另请参阅签名加密算法简介。

注意：您只能使用 <Algorithm> 和 <Algorithms> 这两种元素中的一种元素。

您可以以逗号为分隔符指定多个值。例如“HS256, HS512”或“RS256, PS256”。但是，您不能将 HS* 算法与其他任何算法，或将 ES* 算法与其他任何算法结合使用，因为这两种算法需要特定的密钥类型。您可以将 RS* 算法和 PS* 算法结合使用。

默认	不适用
状态	必需
类型	以英文逗号分隔的值组成的字符串
有效值	HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

使用 <Algorithms> 元素验证加密 JWT。此元素指定创建加密 JWT 时必须使用的密钥加密算法。它还可以选择指定内容加密算法。

注意：您只能使用 <Algorithm> 和 <Algorithms> 这两种元素中的一种元素。

默认	不适用
状态	验证加密 JWT 时必需
类型	复杂

`<Algorithms>` 的子元素

下表提供了 <Algorithms> 的子元素的简要说明：

子元素	是否必需？	说明
`<Key>`	必需	指定密钥的加密算法。
`<Content>`	可选	指定内容的加密算法。

在以下情况下，验证将失败：

加密 JWT 的标头中的 alg 属性中声明的算法与 <Key> 元素中指定的密钥加密算法不同。
政策指定 <Content> 元素，并且加密 JWT 的标头中的 enc 属性中声明的算法与 <Content> 元素中指定的算法不同。

例如，验证加密 JWT 并确认密钥算法为 RSA-OAEP-256 且内容算法为 A128GCM：

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

相反，验证加密 JWT 并确认密钥算法为 RSA-OAEP-256，且不对内容算法强制执行限制条件：

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

密钥加密算法

下表列出了可用的密钥加密算法，以及为使用该密钥加密算法验证 JWT 而必须指定的密钥类型。

`<Key>` 的值（密钥加密算法）	进行验证所需的密钥元素
dir	`<DirectKey>`
RSA-OAEP-256	`<PrivateKey>`
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	`<SecretKey>`
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	`<PasswordKey>`
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	`<PrivateKey>`

请参阅验证加密 JWT 部分，该部分的示例使用的密钥加密算法是 RSA-OAEP-256，因此需要用到 <PrivateKey> 元素。

内容加密算法

VerifyJWT 政策不要求您指定内容加密算法。如果您想指定用于内容加密的算法，请使用 <Algorithms> 元素的 <Content> 子元素来指定。

无论使用什么密钥加密算法，内容加密都支持以下算法（均为对称且基于 AES 的算法）：

A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
A128GCM
A192GCM
A256GCM

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

该政策将验证 JWT 中的受众群体声明是否与配置中指定的值一致。如果不一致，则政策会抛出一个错误。此声明可识别 JWT 的目标接收者。这是 RFC7519 中所述的一种已注册声明。

默认	不适用
状态	可选
类型	字符串
有效值	识别受众群体的流变量或字符串。

<AdditionalClaims/Claim>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

验证 JWT 载荷是否包含指定的附加声明，以及断言的声明值是否一致。

<Claim> 元素支持名为消息模板的动态字符串替换功能。

附加声明使用的名称不是任何一种已注册的标准 JWT 声明名称。附加声明的值可以是字符串、数字、布尔值、映射或数组。映射只是一组名称/值对。您可以在政策配置中明确指定任一类型的声明值，也可以通过引用流变量间接指定。

默认	不适用
状态	可选
类型	字符串、数字、布尔值或映射
数组	设置为 true 可指示值是否为类型数组。默认值：false
有效值	要用于附加声明的任何值。

<Claim> 元素具有以下属性：

名称 -（必需）声明的名称。
注意：请勿在该元素中使用任何已注册声明名称。RFC7519 中列明了已注册声明。它们包括：“iss”“sub”“aud”“iat”“exp”“nbf”和“jti”。
ref -（可选）流变量的名称。如果存在，该政策将使用此变量的值作为声明。如果同时指定了 ref 属性值和明确的声明值，则明确的值则为默认值，并且在引用的流变量未解析的情况下，将使用该值。
类型 -（可选）以下任一项：字符串（默认）、数字、布尔值或映射
数组 -（可选）设置为 true 可指示值是否为类型数组。默认值：false。

添加 <Claim> 元素时，系统会在配置政策时静态设置声明名称。或者，您可以传递 JSON 对象来指定声明名称。因为 JSON 对象是作为变量传递的，所以声明名称是在运行时确定的。

例如：

<AdditionalClaims ref='json_claims'/>

其中，变量 json_claims 包含采用以下格式的 JSON 对象：

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
</AdditionalHeaders>

验证 JWT 标头是否包含指定的附加声明名称/值对，以及断言的声明值是否一致。

<Claim> 元素支持名为消息模板的动态字符串替换功能。

默认	不适用
状态	可选
类型	字符串（默认）、数字、布尔值或映射。如果未指定类型，则类型默认为字符串。
数组	设置为 true 可指示值是否为类型数组。默认值：false
有效值	要用于附加声明的任何值。

<Claim> 元素具有以下属性：

名称 -（必需）声明的名称。
注意：请勿在该元素中使用任何已注册声明名称。RFC7519 中列明了已注册声明。它们包括：“iss”“sub”“aud”“iat”“exp”“nbf”和“jti”。
ref -（可选）流变量的名称。如果存在，该政策将使用此变量的值作为声明。如果同时指定了 ref 属性值和明确的声明值，则明确的值则为默认值，并且在引用的流变量未解析的情况下，将使用该值。
类型 -（可选）以下任一项：字符串（默认）、数字、布尔值或映射
数组 -（可选）设置为 true 可指示值是否为类型数组。默认值：false。

<CustomClaims>

注意：目前，当您通过界面添加新的 GenerateJWT 政策时，系统会插入 CustomClaims 元素。该元素不起作用，忽略即可。请改用正确的元素，即 <AdditionalClaims>。界面将进行更新，以便稍后插入正确的元素。

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

验证 JWT 是否有特定的 jti 声明。当文本值和 ref 属性都为空时，该政策将生成一个包含随机 UUID 的 jti。JWT ID (jti) 声明是 JWT 的唯一标识符。如需详细了解 jti，请参阅 RFC7519。

默认	不适用
状态	可选
类型	字符串或引用。
有效值	字符串或包含 ID 的流变量的名称。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

如果希望在 <KnownHeaders> 元素中没有列出 JWT 的 crit 标头所列任一标头时让政策抛出一个错误，请设置为 false。如果设置为 true，则会使 VerifyJWT 政策忽略 crit 标头。

如果您正在测试环境中，并且尚未准备好处理因标头缺失而导致的失败，则可以将此元素设置为 true。

默认	false
状态	可选
类型	Boolean
有效值	true 或 false

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

如果您希望在 JWT 包含指定未来时间的 iat（颁发时间）声明时让政策抛出一个错误，请设置为 false（默认值）。设置为 true 可让政策在验证过程中忽略 iat。

默认	false
状态	可选
类型	Boolean
有效值	true 或 false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

如果您希望在无法解析政策中指定的任何引用变量时让政策抛出一个错误，请设置为 false。设置为 true 可将所有无法解析的变量都视为空字符串 (null)。

默认	false
状态	可选
类型	Boolean
有效值	true 或 false

<Issuer>

<VerifyJWT name='VJWT-29'>
  ...
  <!-- verify that the iss claim matches a hard-coded value -->
  <Issuer>issuer-string-here</Issuer>

  or:

  <!-- verify that the iss claim matches the value contained in a variable -->
  <Issuer ref='variable-containing-issuer'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>

该政策验证 JWT 中的颁发者（iss 声明）是否与配置元素中指定的字符串一致。iss 声明是 IETF RFC 7519 中所述的已注册声明之一。

默认	不适用
状态	可选
类型	字符串或引用
有效值	不限

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref='variable_containing_headers'/>

GenerateJWT 政策使用 <CriticalHeaders> 元素填充 JWT 中的 crit 标头。例如：

{
  "typ": "...",
  "alg" : "...",
  "crit" : [ "a", "b", "c" ],
}

VerifyJWT 政策会检查 JWT 中的 crit 标头（如果存在），并且对于列出的每个标头，该政策都会检查 <KnownHeaders> 元素是否也列出了该标头。<KnownHeaders> 元素可以包含 crit 中列出的项的超集。只需在 <KnownHeaders> 元素中列出 crit 中列出的所有标头。政策在 crit 中找到的任何未在 <KnownHeaders> 中列出的标头都会导致 VerifyJWT 政策失败。

您可以选择将 VerifyJWT 政策配置为忽略 crit 标头（通过将 <IgnoreCriticalHeaders> 元素设置为 true）。

注意：VerifyJWT 政策不会实际处理 <KnownHeaders> 元素列出的标头。系统会将这些标头保留在代理或后端中，以便您稍后实际对其进行处理。

默认	不适用
状态	可选
类型	以逗号分隔的字符串数组
有效值	数组或包含该数组的变量名称。

<MaxLifespan>

  <VerifyJWT name='VJWT-62'>
  ...
  <!-- hard-coded lifespan of 5 minutes -->
  <MaxLifespan>5m</MaxLifespan>

  or:

  <!-- refer to a variable -->
  <MaxLifespan ref='variable-here'/>

  or:

  <!-- attribute telling the policy to use iat rather than nbf -->
  <MaxLifespan useIssueTime='true'>1h</MaxLifespan>

  or:

  <!-- useIssueTime and ref, and hard-coded fallback value. -->
  <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan>
  ...

配置 VerifyJWT 政策，以确认令牌的有效期不超过指定的阈值。您可以通过使用数字后跟字符（表示秒数、分钟、小时、天或周）来指定阈值。以下字符有效：

s - 秒
m - 分钟
h - 小时
d - 天
w - 周

例如，您可以指定以下值之一：120s、10m、1h、7d、3w。

该政策通过从到期值 (exp) 中减去不早于值 (nbf)，计算令牌的实际有效期。如果缺少 exp 或 nbf，则政策会引发故障。如果令牌有效期超出指定的时间范围，则政策会引发故障。

您可以在计算令牌有效期时将可选属性 useIssueTime 设置为 true 以使用 iat 值，而不是 nbf 值。

可选择使用 MaxLifespan 元素。如果您使用此元素，则只能使用一次。

<PrivateKey>

使用此元素指定可用于验证使用非对称算法加密的 JWT 的私钥。以下是可能的子元素的说明。

<Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

<PrivateKey> 元素的子元素。如有必要，指定政策在验证加密 JWT 时应该用来解密私钥的密码。使用 ref 属性在流变量中传递密码。

默认	不适用
状态	可选
类型	字符串
有效值	流变量引用。注意：您必须指定流变量。由于采用明文指定密码的政策配置无效，因此 Apigee 将拒绝。流变量的前缀必须为“private”。例如 `private.mypassword`

<Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

<PrivateKey> 元素的子元素。指定政策将用于验证加密 JWT 的 PEM 编码的私钥。使用 ref 属性在流变量中传递密钥。

默认	不适用
状态	需要验证已使用非对称密钥加密算法加密的 JWT。
类型	字符串
有效值	包含 PEM 编码 RSA 私钥值的字符串的流变量。注意：流变量的前缀必须为“private”。例如 `private.mykey`

<PublicKey>

为验证使用非对称算法签名的 JWT 所用的公钥指定来源。支持算法包括 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512。以下是可能的子元素的说明。

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
certificate data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

<PublicKey> 元素的子元素。指定用作公钥来源的签名证书。使用 ref 属性在流变量中传递已签名的证书，或直接指定采用 PEM 编码的证书。请确保左侧的证书数据一致，如参考示例所示。

默认	不适用
状态	可选。要验证使用非对称算法签名的 JWT，您必须使用 `<Certificate>`、`<JWKS>` 或 `<Value>` 元素来提供公钥。
类型	字符串
有效值	流变量或字符串。

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

<PublicKey> 元素的子元素。将 JWKS 指定为公钥的来源。这是采用 IETF RFC 7517 - JSON Web 密钥 (JWK) 中所述格式的密钥的列表。

如果入站 JWT 包含 JWKS 中存在的密钥 ID，则该策略将使用恰当的公钥来验证 JWT 签名。如需详细了解此功能，请参阅使用 JSON Web 密钥集 (JWKS) 验证 JWT。

如果您从公开网址提取值，Apigee 会缓存 JWKS，缓存时长为 300 秒。缓存到期时，Apigee 会再次提取 JWKS。

默认	不适用
状态	可选。要验证使用非对称算法签名的 JWT，您必须使用 `<Certificate>`、`<JWKS>` 或 `<Value>` 元素来提供公钥。
类型	字符串
有效值	您可以通过以下四种方式之一指定 JWKS：以文本值形式指定为字面量： <PublicKey> <JWKS>{ "keys": [ {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."}, {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."} ] } </JWKS> </PublicKey> 使用 `ref` 属性通过流变量间接指定： <PublicKey> <JWKS ref="variable-containing-jwks-content"/> </PublicKey> 所引用变量应包含表示 JWKS 的字符串。使用 `uri` 属性通过静态 URI 间接指定： <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> </PublicKey> 使用 `uriRef` 特性通过动态确定的 URI 间接指定： <PublicKey> <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/> </PublicKey>

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

<PublicKey> 元素的子元素。指定用于验证已签名的 JWT 上的签名的公钥。使用 ref 属性在流变量中传递密钥，或直接指定采用 PEM 编码的密钥。请确保左侧的公钥一致，如参考示例所示。

默认	不适用
状态	可选。要验证使用非对称算法签名的 JWT，您必须使用 `<Certificate>`、`<JWKS>` 或 `<Value>` 元素来提供公钥。
类型	字符串
有效值	流变量或字符串。

<RequiredClaims>

<VerifyJWT name='VJWT-1'>
  ...
  <!-- Directly specify the names of the claims to require -->
  <RequiredClaims>sub,iss,exp</RequiredClaims>

  -or-

  <!-- Specify the claim names indirectly, via a context variable -->
  <RequiredClaims ref='claims_to_require'/>
  ...
</VerifyJWT>

<RequiredClaims> 元素是可选字段；它指定验证 JWT 时必须存在于 JWT 载荷中的声明名称列表（以英文逗号分隔）。该元素可确保提供的 JWT 包含所需的声明，但不会验证声明的内容。如果列出的任何声明不存在，则 VerifyJWT 政策将在运行时抛出故障。

默认	不适用
状态	可选
类型	字符串
有效值	使用英文逗号分隔的声明名称列表。

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Value ref="private.your-variable-name"/>
</SecretKey>

SecretKey 元素是可选的。指定在验证使用对称 (HS*) 算法的签名 JWT 或验证使用对称 (AES) 算法进行密钥加密的加密 JWT 时使用的密钥。

`<SecretKey>` 的子项

下表提供了 <SecretKey> 的子元素和属性的说明：

子女状态说明

编码（属性）

可选

子女	状态	说明
编码（属性）	可选	指定在引用的变量中编码密钥的方式。默认情况下，如果不存在 `encoding` 属性，则密钥编码会作为 UTF-8 进行处理。属性的有效值包括：hex、base16、base64 或 base64url。编码值 hex 和 base16 是同义词。 <SecretKey encoding="hex" > <Value ref="private.secretkey"/> </SecretKey> 在上面的示例中，由于编码为 `hex`，因此如果变量 `private.secretkey` 的内容为 `494c6f766541504973`，则密钥会被解码为一组 9 个字节，十六进制是 `49 4c 6f 76 65 41 50 49 73`。注意：Apigee 强制执行最小密钥强度。如需了解详情，请参阅 `Value` 元素的文档。
Value（元素）	必需	编码密钥。指定将用于验证载荷的密钥。使用 `ref` 属性通过变量（例如 `private.secret-key`）间接提供密钥。 <SecretKey> <Value ref="private.my-secret-variable"/> </SecretKey> 注意：变量名称必须包含 private 前缀，如以上示例所示。 Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 字节，HS384 为 48 字节，HS512 则为 64 字节。使用较低强度的密钥会导致运行时错误。

指定在引用的变量中编码密钥的方式。默认情况下，如果不存在 encoding 属性，则密钥编码会作为 UTF-8 进行处理。属性的有效值包括：hex、base16、base64 或 base64url。编码值 hex 和 base16 是同义词。

<SecretKey encoding="hex" >
  <Value ref="private.secretkey"/>
</SecretKey>

在上面的示例中，由于编码为 hex，因此如果变量 private.secretkey 的内容为 494c6f766541504973，则密钥会被解码为一组 9 个字节，十六进制是 49 4c 6f 76 65 41 50 49 73。

注意：Apigee 强制执行最小密钥强度。如需了解详情，请参阅 Value 元素的文档。

Value（元素）

必需

编码密钥。指定将用于验证载荷的密钥。使用 ref 属性通过变量（例如 private.secret-key）间接提供密钥。

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 字节，HS384 为 48 字节，HS512 则为 64 字节。使用较低强度的密钥会导致运行时错误。

<Source>

<Source>jwt-variable</Source>

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

使用此元素，您可以将政策配置为从表单或查询参数变量或任何其他变量中检索 JWT。如果此元素存在，政策将不会删除可能存在的任何 Bearer 前缀。如果变量不存在，或者政策未在指定变量中找到 JWT，则政策会返回错误。

默认情况下，如果 <Source> 元素不存在，政策会通过读取变量 request.header.authorization 并删除 Bearer 前缀来检索 JWT。如果您在 Authorization 标头中将 JWT 作为不记名令牌（具有 Bearer 前缀）传递，请不要在政策配置中指定 <Source> 元素。例如，如果您按如下所示在 Authorization 标头中传递 JWT，则不使用 <Source> 元素：

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."

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

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

该政策验证 JWT 中的主题（sub 声明）是否与政策配置中指定的字符串一致。sub 声明是 RFC7519 中所述的已注册声明之一。

默认	不适用
状态	可选
类型	字符串
有效值	唯一标识主题的任何值。

<TimeAllowance>

<VerifyJWT name='VJWT-23'>
  ...
  <!-- configure a hard-coded time allowance of 20 seconds -->
  <TimeAllowance>20s</TimeAllowance>

  or:

  <!-- refer to a variable containing the time allowance -->
  <TimeAllowance ref='variable-containing-time-allowance'/>

  or:

  <!-- refer to a variable; fallback to a hard-coded value if the variable is empty -->
  <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>

时间的“宽限期”，用于考虑 JWT 颁发者与验证者之间的时钟偏差。这适用于到期时间（exp 声明）以及“不早于”时间（nbf 声明）。例如，如果将时间宽限设置为 30s 秒，则在宣布到期后的 30 秒内，已过期的 JWT 仍将被视为有效。“不早于”时间将采用类似的方式估算。

默认	0 秒（无宽限期）
状态	可选
类型	字符串
有效值	时间跨度表达式，或是对包含表达式的流变量的引用。时间跨度可以通过一个正整数指定，后跟一个表示时间单位的字符，如下所示： s = 秒 m = 分钟 h = 小时 d = 天

<Type>

<Type>type-string-here</Type>

描述政策是验证签名 JWT 还是加密 JWT。<Type> 元素是可选字段；您可以用它来说明配置的政策是生成签名 JWT 还是加密 JWT。

如果设置了 <Type> 元素：
- 如果 <Type> 的值为 Signed，则政策会验证签名 JWT，并且必须设置 <Algorithm> 元素。
- 如果 <Type> 的值为 Encrypted，则政策会验证加密 JWT，并且必须设置 <Algorithms> 元素。
如果未设置 <Type> 元素：
- 如果设置了 <Algorithm> 元素，则政策假定 <Type> 为 Signed。
- 如果设置了 <Algorithms> 元素，则政策假定 <Type> 为 Encrypted。
如果 <Algorithm> 和 <Algorithms> 均未设置，则配置无效。

默认	不适用
状态	可选
类型	字符串
有效值	`Signed` 或 `Encrypted`。

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 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.jwt.AlgorithmInTokenNotPresentInConfiguration`	`401`	Occurs when the verification policy has multiple algorithms.
`steps.jwt.AlgorithmMismatch`	`401`	The algorithm specified in the `Generate` policy did not match the one expected in the `Verify` policy. The algorithms specified must match.
`steps.jwt.FailedToDecode`	`401`	The policy was unable to decode the JWT. The JWT is possibly corrupted.
`steps.jwt.GenerationFailed`	`401`	The policy was unable to generate the JWT.
`steps.jwt.InsufficientKeyLength`	`401`	For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
`steps.jwt.InvalidClaim`	`401`	For a missing claim or claim mismatch, or a missing header or header mismatch.
`steps.jwt.InvalidConfiguration`	`401`	Both the `<Algorithm>` and `<Algorithms>` elements are present.
`steps.jwt.InvalidCurve`	`401`	The curve specified by the key is not valid for the Elliptic Curve algorithm.
`steps.jwt.InvalidIterationCount`	`401`	The iteration count that was used in the encrypted JWT is not equal to the iteration count specified in the VerifyJWT policy configuration. This applies only to JWT that use `<PasswordKey>`.
`steps.jwt.InvalidJsonFormat`	`401`	Invalid JSON found in the header or payload.
`steps.jwt.InvalidKeyConfiguration`	`401`	`JWKS` in the `<PublicKey>` element is invalid. The reason could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint as a target.
`steps.jwt.InvalidSaltLength`	`401`	The salt length that was used in the encrypted JWT is not equal to the salt length specified in the VerifyJWT policy configuration. This applies only to JWT that use `<PasswordKey>`.
`steps.jwt.InvalidPasswordKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidPrivateKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidPublicKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidSecretKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidToken`	`401`	This error occurs when the JWT signature verification fails.
`steps.jwt.JwtAudienceMismatch`	`401`	The audience claim failed on token verification.
`steps.jwt.JwtIssuerMismatch`	`401`	The issuer claim failed on token verification.
`steps.jwt.JwtSubjectMismatch`	`401`	The subject claim failed on token verification.
`steps.jwt.KeyIdMissing`	`401`	The `Verify` policy uses a JWKS as a source for public keys, but the signed JWT does not include a `kid` property in the header.
`steps.jwt.KeyParsingFailed`	`401`	The public key could not be parsed from the given key information.
`steps.jwt.NoAlgorithmFoundInHeader`	`401`	Occurs when the JWT contains no algorithm header.
`steps.jwt.NoMatchingPublicKey`	`401`	The `Verify` policy uses a JWKS as a source for public keys, but the `kid` in the signed JWT is not listed in the JWKS.
`steps.jwt.SigningFailed`	`401`	In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
`steps.jwt.TokenExpired`	`401`	The policy attempts to verify an expired token.
`steps.jwt.TokenNotYetValid`	`401`	The token is not yet valid.
`steps.jwt.UnhandledCriticalHeader`	`401`	A header found by the Verify JWT policy in the `crit` header is not listed in `KnownHeaders`.
`steps.jwt.UnknownException`	`401`	An unknown exception occurred.
`steps.jwt.WrongKeyType`	`401`	Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

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

Error name	Cause	Fix
`InvalidNameForAdditionalClaim`	The deployment will fail if the claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is one of the following registered names: `kid`, `iss`, `sub`, `aud`, `iat`, `exp`, `nbf`, or `jti`.
`InvalidTypeForAdditionalClaim`	If the claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is not of type `string`, `number`, `boolean`, or `map`, the deployment will fail.
`MissingNameForAdditionalClaim`	If the name of the claim is not specified in the child element `<Claim>` of the `<AdditionalClaims>` element, the deployment will fail.
`InvalidNameForAdditionalHeader`	This error ccurs when the name of the claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is either `alg` or `typ`.
`InvalidTypeForAdditionalHeader`	If the type of claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is not of type `string`, `number`, `boolean`, or `map`, the deployment will fail.
`InvalidValueOfArrayAttribute`	This error occurs when the value of the array attribute in the child element `<Claim>` of the `<AdditionalClaims>` element is not set to `true` or `false`.
`InvalidValueForElement`	If the value specified in the `<Algorithm>` element is not a supported value, the deployment will fail.
`MissingConfigurationElement`	This error will occur if the `<PrivateKey>` element is not used with RSA family algorithms or the `<SecretKey>` element is not used with HS Family algorithms.
`InvalidKeyConfiguration`	If the child element `<Value>` is not defined in the `<PrivateKey>` or `<SecretKey>` elements, the deployment will fail.
`EmptyElementForKeyConfiguration`	If the ref attribute of the child element `<Value>` of the `<PrivateKey>` or `<SecretKey>` elements is empty or unspecified, the deployment will fail.
`InvalidConfigurationForVerify`	This error occurs if the `<Id>` element is defined within the `<SecretKey>` element.
`InvalidEmptyElement`	This error occurs if the `<Source>` element of the Verify JWT policy is empty. If present, it must be defined with an Apigee flow variable name.
`InvalidPublicKeyValue`	If the value used in the child element `<JWKS>` of the `<PublicKey>` element does not use a valid format as specified in RFC 7517, the deployment will fail.
`InvalidConfigurationForActionAndAlgorithm`	If the `<PrivateKey>` element is used with HS Family algorithms or the `<SecretKey>` element is used with RSA Family algorithms, the deployment will fail.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "InvalidToken"`
`JWT.failed`	All JWT policies set the same variable in the case of a failure.	`JWT.failed = true`

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

    <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>

验证 JWT 政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

是什么

方式

视频

验证签名 JWT

签名 JWT 的示例

HS256 算法

RS256 算法

设置密钥元素以验证签名 JWT

验证加密 JWT

加密 JWT 的示例

设置密钥元素以验证加密 JWT

元素参考

适用于顶级元素的属性

<DisplayName>

<Algorithm>

<Algorithms>

<Algorithms> 的子元素

密钥加密算法

内容加密算法

<Audience>

<AdditionalClaims/Claim>

<AdditionalHeaders/Claim>

<CustomClaims>

<Id>

<IgnoreCriticalHeaders>

<IgnoreIssuedAt>

<IgnoreUnresolvedVariables>

<Issuer>

<KnownHeaders>

<MaxLifespan>

<PrivateKey>

<Password>

<Value>

<PublicKey>

<Certificate>

<JWKS>

<Value>

<RequiredClaims>

<SecretKey>

<SecretKey> 的子项

<Source>

<Subject>

<TimeAllowance>

<Type>

Flow variables

错误参考信息

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

验证 JWT 政策

`<Algorithms>` 的子元素

`<SecretKey>` 的子项