验证 JWT 政策

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

内容

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

执行此政策时，Edge 会验证 JWT 的签名，并验证 JWT 是 根据过期时间有效。（可选）该政策还可以验证 JWT 中特定声明的值，例如主题、颁发者、受众群体或附加声明的值。

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

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

视频

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

示例

• 验证采用 HS256 算法签名的 JWT
• 验证采用 RS256 算法签名的 JWT

验证采用 HS256 算法签名的 JWT

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

策略配置包含 Edge 解码和评估 JWT 所需的信息， 例如，在何处查找 JWT（在 Source 元素中指定的流变量中） 签名算法，密钥的位置（存储在 Edge 流变量中， 而一组必需的声明及其 值。

<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 算法签名的 JWT

此示例政策验证了采用 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 代理中的后续政策或条件检查这些值。如需查看此政策设置的变量列表，请参阅流变量。

设置密钥元素

用来指定验证 JWT 的密钥的元素取决于所选算法，如下表所示：

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

<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 政策”的元素和属性。

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

适用于顶级元素的属性

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

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

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

<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 载荷是否包含指定的附加声明，以及断言的声明值是否一致。

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

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

• 名称 -（必需）声明的名称。
• 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 标头是否包含指定的附加声明名称/值对，以及断言的声明值是否一致。

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

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

• 名称 -（必需）声明的名称。
• 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。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

而将此元素设置为 true 的一个原因是如果您正在测试环境中并且尚未就绪，这会造成缺失的标头失败。

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

该政策验证 JWT 中的颁发者是否与配置元素中指定的字符串一致。用于识别 JWT 颁发者的声明。这是 RFC7519 中所述的一组已注册声明组。

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

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

指定用于验证 JWT 签名的签名证书。使用 ref 属性在流变量中传递已签名的证书，或直接指定采用 PEM 编码的证书。仅在算法是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一时使用。

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

指定包含一组采用 JWKS 格式的公钥 (RFC 7517) 的值。仅在算法是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一时使用。

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

如果您从公开网址提取该值，Edge 会将 JWKS 缓存 300 秒。 缓存过期后，Edge 会再次提取 JWKS。

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

指定用于验证 JWT 签名的公钥或公共证书。使用 ref 属性在流变量中传递密钥/证书，或直接指定采用 PEM 编码的密钥。仅在算法是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一时使用。

<SecretKey/Value>

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

提供用于验证或签署使用 HMAC 算法的令牌的密钥。仅供使用 （当算法为 HS256、HS384 或 HS512 之一时）。

<Source>

<Source>jwt-variable</Source>

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

<Subject>

<Subject>subject-string-here</Subject>

政策会验证 JWT 中的主题是否与政策配置中指定的字符串一致。此声明用于标识或陈述 JWT 的主题。这是 RFC7519 中所述的标准声明组之一。

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

时间的“宽限期”。例如，如果将时间宽限设置为 60 秒，则在宣布到期后的 60 秒，已过期的 JWT 仍将被视为有效。“不早于”时间将采用类似的方式估算。默认值为 0 秒（无宽限期）。

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)

错误参考信息

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.

Deployment errors

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

故障变量

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

错误响应示例

处理错误时，最佳做法是捕获错误响应的 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>