本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
内容
验证从客户端或其他系统收到的 JWS 签名。此政策还会将标头提取到上下文变量中，这样后续政策或条件就可以检查这些值，以做出授权或路由决策。如需查看详细介绍，请参阅 JWS 和 JWT 政策概览。
如果 JWS 已经过验证且有效，则允许该请求继续。如果 JWS 签名无法验证，或者 JWS 因某种类型的错误而无效，则系统会停止所有处理并在响应中返回错误。
此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。
如需了解 JWS 的各个部分以及如何进行加密和签名，请参阅 RFC7515。
视频
观看视频短片，了解如何验证 JWS 签名。虽然此视频专用于验证 JWT，但其中的许多概念同样适用于 JWS。
示例
验证采用 HS256 算法签名的已连接 JWS
此示例政策验证了采用 HS256 加密算法（即使用 SHA-256 校验和的 HMAC）进行签名的已连接 JWS。JWS 会使用名为 JWS 的表单参数在代理请求中传递 JWS。该密钥包含在名为 private.secretkey 的变量中。
连接的 JWS 包含已编码的标头、载荷和签名：
header.payload.signature
政策配置包括 Apigee 解码和评估 JWS 需要的信息，例如在哪里查看 JWS（在 <Source> 元素中指定的流变量中）、所需的签名算法、在哪里查看密钥（例如，存储在可从 Apigee KVM 检索的 Apigee 流变量中）。
<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 的密钥的元素取决于所选算法，如下表所示：
| 算法 | 密钥元素 | |
|---|---|---|
| HS* |
<SecretKey> <Value ref="private.secretkey"/> </SecretKey> |
|
| RS*、ES*、PS* | <PublicKey> <Value ref="rsa_public_key"/> </PublicKey> 或者： <PublicKey> <JWKS ref="jwks_val_ref_or_url"/> </PublicKey> |
|
| *如需详细了解密钥要求，请参阅签名加密算法简介。 | ||
元素参考
“政策参考”介绍了“验证 JWS 政策”的元素和属性。
注意：配置因您使用的加密算法而有些许差异。如需查看演示特定用例配置的示例，请参阅示例。
S适用于顶级元素的属性
<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">
以下属性是所有政策的父级元素都具有的属性。
| 属性 | 说明 | 默认 | Presence |
|---|---|---|---|
| name |
政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。但是，Apigee 界面会实施其他限制，例如自动移除非字母数字字符。（可选）使用 |
不适用 | 必需 |
| continueOnError |
设置为 false 可在政策失败时返回错误。对于大多数政策来说，这一行为符合预期。设置为 |
false | 可选 |
| 已启用 | 设置为 true 可实施政策。设置为 |
true | 可选 |
| async | 此属性已弃用。 | false | 已弃用 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了用于名称属性之外，还可以用于在 Apigee 界面代理编辑器中给政策添加不同的自然语言名称标签。
| 默认 | 如果省略此元素，则会使用政策的名称属性的值。 |
| Presence | 可选 |
| 类型 | 字符串 |
<Algorithm>
<Algorithm>HS256</Algorithm>
指定用于签署令牌的加密算法。RS*/PS*/ES* 算法使用公钥/密钥对，而 HS* 算法使用共享密钥。另请参阅签名加密算法简介。
您可以以逗号为分隔符指定多个值。例如“HS256, HS512”或“RS256, PS256”。但是，您不能将 HS* 算法与其他任何算法，或将 ES* 算法与其他任何算法结合使用，因为这两种算法需要特定的密钥类型。您可以将 RS* 算法和 PS* 算法结合使用。
| 默认 | 不适用 |
| Presence | 必需 |
| 类型 | 以英文逗号分隔的值组成的字符串 |
| 有效值 | HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 |
<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 声明名称。附加声明的值可以是字符串、数字、布尔值、映射或数组。映射只是一组名称/值对。您可以在政策配置中明确指定任一类型的声明值，也可以通过引用流变量间接指定。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 |
字符串（默认）、数字、布尔值或映射。 如果未指定类型，则类型默认为字符串。 |
| 数组 | 设置为 true 可指示值是否为类型数组。默认值：false |
| 有效值 | 要用于附加声明的任何值。 |
<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）。
| 默认 | N/A |
| Presence | 可选 |
| 类型 | 变量引用 |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
如果希望在 <KnownHeaders> 元素中没有列出 JWS 的 crit 标头所列任一标头时让政策抛出一个错误，请设置为 false。如果设置为 true，则会使 VerifyJWS 政策忽略 crit 标头。
将此元素设置为 true 的一个原因在于，如果您正在测试环境中，并且不希望政策因缺少标头而失败。
| 默认 | false |
| Presence | 可选 |
| 类型 | 布尔值 |
| 有效值 | true 或 false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
如果您希望在无法解析政策中指定的任何引用变量时让政策抛出一个错误，请设置为 false。设置为 true 可将所有无法解析的变量都视为空字符串 (null)。
| 默认 | false |
| Presence | 可选 |
| 类型 | 布尔值 |
| 有效值 | true 或 false |
<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）。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 | 以逗号分隔的字符串数组 |
| 有效值 | 数组或包含该数组的变量名称。 |
<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。
如果您从公开网址提取值，Apigee 会缓存 JWKS，缓存时长为 300 秒。缓存到期时，Apigee 会再次提取 JWKS。
| 默认 | 不适用 |
| Presence | 要验证使用 RSA 算法的 JWS，您必须使用 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 之一时使用。
| 默认 | 不适用 |
| Presence | 要验证使用 RSA 算法签名的 JWS，您必须使用 JWKS 或值元素。 |
| 类型 | 字符串 |
| 有效值 | 流变量或字符串。 |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Value ref="private.your-variable-name"/> </SecretKey>
指定在验证使用对称 (HS*) 算法（HS256、HS384 或 HS512 之一）的 JWS 时使用的密钥。
该元素是可选的。但是，您必须仅添加 <PublicKey> 或 <SecretKey> 元素之一。验证算法为 RS*、PS* 或 ES* 的 JWS 时使用 <PublicKey> 元素，验证算法为 HS* 的 JWS 时使用 <SecretKey> 元素。
<SecretKey> 的子项
下表提供了 <SecretKey> 的子元素和属性的说明：
| 子女 | Presence | 说明 |
|---|---|---|
| 编码（属性） | 可选 | 指定在引用的变量中编码密钥的方式。默认情况下，如果不存在 <SecretKey encoding="base64" > <Value ref="private.secretkey"/> </SecretKey> 在上面的示例中，由于编码为 |
| Value（元素） | 必需 | 编码密钥。指定将用于验证载荷的密钥。使用 <SecretKey> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 字节，HS384 为 48 字节，HS512 则为 64 字节。使用较低强度的密钥会导致运行时错误。 |
<Source>
<Source>JWS-variable</Source>
如果存在，请指定政策在其中查找要验证的 JWS 的流变量。
| 默认 | request.header.authorization（请参阅上述“注意”部分，了解有关默认值的重要信息。） |
| Presence | 可选 |
| 类型 | 字符串 |
| 有效值 | Apigee 流变量名称。 |
<Type>
<Type>type-string-here</Type>
可选元素，唯一允许的值是 Signed，用于指定政策验证签名 JWS。提供的 <Type> 仅用于匹配 GenerateJWT 和 VerifyJWT 政策的相应元素（可以接受值 Signed 或 Encrypted）。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 | 字符串 |
| 有效值 | Signed |
流变量
成功后，验证 JWS 和解码 JWS 政策将根据此模式设置上下文变量：
jws.{policy_name}.{variable_name}
例如，如果政策名称为 verify-jws，则该政策会将 JWS 中指定的算法存储在此上下文变量中：jws.verify-jws.header.algorithm
| 变量名称 | 说明 |
|---|---|
decoded.header.name |
载荷中标头的 JSON 可解析值。为载荷中的每个标头设置一个变量。虽然您还可以使用 header.name 流变量，但建议使用此变量来访问标头。 |
header.algorithm |
JWS 中使用的签名算法。例如 RS256、HS384 等。如需了解详情，请参阅（算法）标头参数。 |
header.kid |
生成 JWS 时添加的密钥 ID。另请参阅 JWT 和 JWS 政策概览中的“使用 JSON 网络密钥集 (JWKS)”来验证 JWS。如需了解详情，请参阅（密钥 ID）标头参数。 |
header.type |
标头类型值。如需了解详情，请参阅（类型）标头参数。 |
header.name |
已命名标头的值（标准或附加）。将为 JWS 标头部分中的每个附加标头设置其中一个。 |
header-json |
JSON 格式的标头。 |
payload |
如果 JWS 具有附加的载荷，则为 JWS 载荷。对于分离的载荷，此变量为空。 |
valid |
对于 VerifyJWS，在验证签名时，此变量为 true，而且当前时间在令牌有效期之前且在令牌 notBefore 值之后（如果两者存在）。否则为 false。 对于 DecodeJWS，无需设置此变量。 |
错误参考信息
本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 发生的条件 |
|---|---|---|
steps.jws.AlgorithmInTokenNotPresentInConfiguration |
401 |
验证政策包含多个算法时发生。 |
steps.jws.AlgorithmMismatch |
401 |
由 Generate 政策在标头中指定的算法与 Verify 政策中要求的算法不匹配。指定的算法必须匹配。 |
steps.jws.ContentIsNotDetached |
401 |
当 JWS 不包含分离的内容载荷时，系统会指定 <DetachedContent>。 |
steps.jws.FailedToDecode |
401 |
该政策无法解码 JWS。JWS 可能已损坏。 |
steps.jws.InsufficientKeyLength |
401 |
HS256 算法的密钥小于 32 个字节 |
steps.jws.InvalidClaim |
401 |
用于缺失声明或声明不匹配，或者缺少标题或标头不匹配的情况。 |
steps.jws.InvalidCurve |
401 |
密钥指定的曲线对椭圆曲线算法无效。 |
steps.jws.InvalidJsonFormat |
401 |
可在 JWS 标头中找到无效的 JSON。 |
steps.jws.InvalidJws |
401 |
当 JWS 签名验证失败时，会发生此错误。 |
steps.jws.InvalidPayload |
401 |
JWS 负载无效。 |
steps.jws.InvalidSignature |
401 |
省略 <DetachedContent> 并且 JWS 具有分离的内容负载。 |
steps.jws.KeyIdMissing |
401 |
Verify 政策使用 JWKS 作为公钥的来源，但已签名的 JWS 不包含标头中的 kid 属性。 |
steps.jws.KeyParsingFailed |
401 |
无法通过给定密钥信息解析公钥。 |
steps.jws.MissingPayload |
401 |
JWS 负载缺失。 |
steps.jws.NoAlgorithmFoundInHeader |
401 |
在 JWS 省略算法标头时发生。 |
steps.jws.NoMatchingPublicKey |
401 |
Verify 政策使用 JWKS 作为公钥的来源，但已签名的 JWS 中的 kid 未列在 JWKS 中。 |
steps.jws.UnhandledCriticalHeader |
401 |
验证 JWS 政策在 crit 标头中发现的标头未在 KnownHeaders 中列出。 |
steps.jws.UnknownException |
401 |
发生未知异常。 |
steps.jws.WrongKeyType |
401 |
指定的密钥类型不正确。例如，为椭圆曲线算法指定 RSA 密钥，或为 RSA 算法指定了曲线密钥。 |
部署错误
在您部署包含此政策的代理时，可能会发生这些错误。
| 错误名称 | 发生的条件 |
|---|---|
InvalidAlgorithm |
唯一的有效值为：RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512。 |
|
|
其他可能的部署错误。 |
故障变量
发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。
| 变量 | 地点 | 示例 |
|---|---|---|
fault.name="fault_name" |
fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 | fault.name Matches "TokenExpired" |
JWS.failed |
所有 JWT 政策都将在发生故障时设置同一变量。 | jws.JWS-Policy.failed = true |
错误响应示例
处理错误时，最佳做法是捕获错误响应的 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>