VerifyJWS 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

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

如果 JWS 已经过验证且有效，则允许该请求继续。如果 JWS 签名无法验证，或者 JWS 因某种类型的错误而无效，则系统会停止所有处理并在响应中返回错误。

如需了解 JWS 的各个部分以及如何进行加密和签名，请参阅 RFC7515。

视频

观看视频短片，了解如何验证 JWS 签名。虽然此视频专用于验证 JWT，但其中的许多概念同样适用于 JWS。

示例

• 验证采用 HS256 算法签名的已连接 JWS
• 验证使用 RS256 算法签名的已分离 JWS

验证采用 HS256 算法签名的已连接 JWS

此示例政策验证了采用 HS256 加密算法（即使用 SHA-256 校验和的 HMAC）进行签名的已连接 JWS。JWS 会使用名为 JWS 的表单参数在代理请求中传递 JWS。该密钥包含在名为 private.secretkey 的变量中。

连接的 JWS 包含已编码的标头、载荷和签名：

header.payload.signature

政策配置包含 Edge 解码和评估 JWS 所需的信息，例如在哪里可以找到 JWS（在 <Source> 元素中指定的流变量中）、所需的签名算法，以及在哪里查找密钥（存储在 Edge 流变量中，例如可以从 Edge KVM 中检索的密钥）。

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

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

验证使用 RS256 算法签名的已分离 JWS

此示例政策可验证使用 RS256 算法签名的已分离 JWS。要进行验证，您需要提供公钥。JWS 会使用名为 JWS 的表单参数在代理请求中传递 JWS。公钥包含在名为 public.publickey 的变量中。

分离的 JWS 会忽略 JWS 中的载荷：

header..signature

因此，您应将包含载荷的变量名称指定给 <DetachedContent> 元素，以将该载荷传递给 VerifyJWS 政策。<DetachedContent> 中指定的内容必须采用未经编码的原始格式，即创建 JWS 签名时的格式。

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

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

设置密钥元素

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

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

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

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

元素参考

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

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

适用于顶级元素的属性

<VerifyJWS name="JWS" 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* 算法结合使用。

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

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

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

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

• 名称 -（必需）声明的名称。
• ref -（可选）流变量的名称。如果存在，该政策将使用此变量的值作为声明。如果同时指定了 ref 属性值和明确的声明值，则明确的值则为默认值，并且在引用的流变量未解析的情况下，将使用该值。
• 类型 -（可选）以下任一项：字符串（默认）、数字、布尔值或映射
• 数组 -（可选）设置为 true 可指示值是否为类型数组。默认值：false。

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

生成的带有内容载荷的 JWS 采用以下格式：

header.payload.signature

如果您使用 GenerateJWS 政策创建分离的载荷，则生成的 JWS 将省略载荷且采用如下格式：

header..signature

因此，对于分离的载荷，您应使用 <DetachedContent> 元素将载荷传递给 VerifyJWS 政策。指定的内容载荷必须采用未经编码的原始格式，即创建 JWS 签名时的格式。

该政策在以下情况下会抛出错误：

• 当 JWS 不包含分离的内容载荷时指定 <DetachedContent>（故障代码为 steps.jws.ContentIsNotDetached）。
• 省略 <DetachedContent> 并且 JWS 具有分离的内容载荷（故障代码为 steps.jws.InvalidSignature）。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

将此元素设置为 true 的一个原因在于，如果您正在测试环境中，并且不希望政策因缺少标头而失败。

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

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

<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 之一时使用。

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

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

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</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>

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

提供用于验证或签署使用 HMAC 算法的令牌的密钥。仅在算法是 HS256、HS384、HS512 之一时使用。 使用 ref 属性在流变量中传递密钥。

<Source>

<Source>JWS-variable</Source>

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

流变量

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

jws.{policy_name}.{variable_name}

例如，如果政策名称为 verify-jws，则该政策会将 JWS 中指定的算法存储在此上下文变量中：jws.verify-jws.header.algorithm

错误参考信息

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

运行时错误

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

部署错误

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

故障变量

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

错误响应示例

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