本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
内容
生成一个已签名的 JWS，其中包含一组可配置的声明。随后，可将 JWS 返回到客户端、传输到后端目标或以其他方式使用。如需查看详细介绍，请参阅 JWS 和 JWT 政策概览。
如需了解 JWS 的各个部分以及如何进行加密和签名，请参阅 RFC7515。
此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。
视频
观看视频短片，了解如何生成已签名的 JWT。 虽然此视频专用于生成 JWT，但其中的许多概念同样适用于 JWS。
示例
生成使用 HS256 签名的 JWS
此示例政策会生成使用 HS256 算法签名的 JWS。HS256 依赖共享密钥来签署和验证签名。 该 JWS 使用“附加”内容，这意味着编码标头、载荷和签名以点间方式连接以生成最终 JWS：
[header].[payload].[signature]
使用 <Payload> 元素指定未编码的原始 JWS 载荷。在此示例中，变量包含载荷。当触发此政策操作时，Apigee 会对 JWS 标头和载荷进行编码，然后添加编码的签名以对 JWS 进行数字签名。
下面的政策配置根据变量 my-payload 中包含的载荷创建 JWS，并将生成的 JWS 存储在变量 output-variable 中。
<GenerateJWS name="JWS-Generate-HS256"> <DisplayName>JWS Generate HS256</DisplayName> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> <Payload ref="my-payload"/> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
生成 HS256 签名的 JWT
此示例还会生成一个 JWS，其中包含使用 HS256 算法签名的附加内容。在这种情况下，载荷为 JSON。将 typ 标头设置为 JWT 会生成已签名的 JWS（也是已签名的 JWT）。（参考）
下面的政策配置根据变量 json-content 中包含的载荷创建 JWS，并将生成的 JWS 存储在变量 output-variable 中。当且仅当 json-content 变量包含 JSON 载荷且该 JSON 载荷中的属性对 JWT 有效时，结果才会是已签名的 JWT。例如，exp 属性（如果存在）必须包含数值。aud 属性（如果存在）必须是字符串或字符串数组。等等。 如需详细了解 JWT 声明的有效值，请参阅 IETF RFC7519。
<GenerateJWS name="JWS-Generate-HS256-JWT"> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <Payload ref="json-content"/> <AdditionalHeaders> <Claim name="typ">JWT</Claim> </AdditionalHeaders> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
生成已分离的 JWS
此示例政策会生成已分离内容的 JWS，使用 RS256 算法签名。生成 RS256 签名依赖于 RSA 私钥，此私钥必须以 PEM 编码格式提供。
已分离内容的 JWS 会忽略已生成的 JWS 中的载荷：
[header]..[signature]
使用 <Payload> 元素指定未编码的原始 JWS 载荷。当触发此政策时，Apigee 会编码 JWS 标头和载荷，然后使用它们生成编码的签名。但是，生成的 JWS 会忽略序列化 JWS 中的已编码载荷。当签名内容很大，或为二进制文件（如图片或 PDF）时或两者兼具时，此功能非常有用。如要允许验证，您必须将签名内容中的元素、JWS 和载荷传递给验证方。如果您使用 VerifyJWS 政策验证 JWS，则可以使用 VerifyJWS 政策的 <DetachedContent> 元素指定包含载荷的变量。
<GenerateJWS name="JWS-Generate-RS256"> <DisplayName>JWS Generate RS256</DisplayName> <Algorithm>RS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> <Payload ref="my-payload"/> <DetachContent>true</DetachContent> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
设置密钥元素
您用来指定用于生成 JWS 的密钥的元素取决于所选算法，如下表所示：
| 算法 | 密钥元素 | |
|---|---|---|
| HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> |
|
| RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey>
|
|
| *如需详细了解密钥要求，请参阅签名加密算法简介。 | ||
生成 JWS 的元素参考
政策参考介绍了“生成 JWS”政策的元素和属性。
注意：配置因您使用的加密算法而有些许差异。如需查看演示特定用例配置的示例，请参阅示例。
适用于顶级元素的属性
<GenerateJWS 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>algorithm-here</Algorithm>
指定用于签署令牌的加密算法。
| 默认 | 不适用 |
| 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 的标头中放置额外的声明名称/值对。
| 默认 | 不适用 |
| Presence | 可选 |
| 有效值 | 要用于附加声明的任何值。您可以将声明显式指定为字符串、数字、布尔值、映射或数组。 |
<Claim> 元素具有以下属性：
- 名称 -（必需）声明的名称，也称为参数。
- ref -（可选）流变量的名称。如果存在，该政策将使用此变量的值作为声明。如果同时指定了 ref 属性值和明确的声明值，则明确的值则为默认值，并且在引用的流变量未解析的情况下，将使用该值。
- 类型 -（可选）以下任一项：字符串（默认）、数字、布尔值或映射
- 数组 -（可选）设置为 true 可指示值是否为类型数组。默认值：false。
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref="variable_containing_headers"/>
将关键标头 crit 添加到 JWS。crit 标头是必须已知且 JWS 接收者可识别的标头名称数组。例如，您可以使用此配置元素生成解码后的 JWS 标头，如下所示：
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}此 JWS 标头声明 hyb 标头参数至关重要，JWS 的任何收件人都必须了解该参数的含义和值。
根据 IETF RFC 7515，如果收件人不理解 crit 参数中引用的一个或多个参数，则 JWS 的收件人应将 JWS 拒绝为无效。在 Apigee 中，VerifyJWS 政策符合此行为。对于 crit 参数中列出的每个参数，它会检查 VerifyJWS 政策的 <KnownHeaders> 元素是否也列出该参数。VerifyJWS 政策在 crit 中找到但未同时在 <KnownHeaders> 中列出的任何标头都会导致 VerifyJWS 政策拒绝该 JWS。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 | 以逗号分隔的一个或多个字符串的数组 |
| 有效值 | 数组或对包含数组的变量的引用。 |
<DetachContent>
<DetachContent>true|false</DetachContent>
指定是否生成具有已分离载荷的 JWS（<DetachContent>true</DetachContent>，否则为 <DetachContent>false</DetachContent>）。
如果指定 false，则在默认情况下，生成的 JWS 采用以下格式：
[header].[payload].[signature]
如果指定 true 以创建具有已分离载荷的 JWS，则生成的 JWS 会省略载荷并采用以下格式：
[header]..[signature]
通过使用分离载荷的 JWS，您应自行将未编码的原始载荷与序列化 JWS 一起传递给验证方。
| 默认 | false |
| Presence | 可选 |
| 类型 | 布尔值 |
| 有效值 | true 或 false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
如果您希望在无法解析政策中指定的任何引用变量时让政策抛出一个错误，请设置为 false。设置为 true 可将所有无法解析的变量都视为空字符串 (null)。
| 默认 | false |
| Presence | 可选 |
| 类型 | 布尔值 |
| 有效值 | true 或 false |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
指定政策将使用生成的 JWS 设置的上下文变量的名称。默认情况下，该政策会将 JWS 放在名为 jws.POLICYNAME.generated_jws 的上下文变量中。
| 默认 | jws.POLICYNAME.generated_jws |
| Presence | 可选 |
| 类型 | 字符串（流变量名称） |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
指定未编码的原始 JWS 载荷。指定包含载荷的变量，或者指定一个字符串。
| 默认 | 不适用 |
| Presence | 必需 |
| 类型 | 字符串、字节数组、流或未编码的 JWS 载荷的任何其他表示形式。 |
| 有效值 | 消息模板或对包含载荷的变量的引用。 |
<PrivateKey> 元素
可选，仅在 <Algorithm> 是 RS*、PS* 或 ES* 选项之一时使用。它指定用于签名的私钥，以及与私钥相关的其他信息。该算法适用于非对称算法。
<PrivateKey> <Value ref="private.privatekey"</Value> </PrivateKey>
| 默认： | 不适用 |
| 状态： | 可选。但是，您必须准确添加 <PrivateKey> 或 <SecretKey> 元素之一。如果算法为 RS*、PS* 或 ES*，请使用 <PrivateKey> 元素；如果算法为 HS*，则使用 <SecretKey> 元素。 |
| 类型： | 不适用 |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
指定要包含在 JWS 标头中的密钥 ID (kid)。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 | 字符串 |
| 有效值 | 流变量或字符串 |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
根据需要指定政策应用来解密私钥的密码。使用 ref 属性在流变量中传递密钥。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 | 字符串 |
| 有效值 |
流变量引用。 注意：您必须使用 ref 属性指定流变量。由于采用明文指定密码的政策配置无效，因此 Apigee 将拒绝。流变量的前缀必须为“private”。例如 |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
指定用于为 JWS 签名的 PEM 编码私钥。使用 ref 属性在流变量中传递密钥。
| 默认 | 不适用 |
| Presence | 使用政策通过 RS*、PS* 或 ES* 算法之一生成 JWS 时是必需的。 |
| 类型 | 字符串 |
| 有效值 | 包含 PEM 编码 私钥值的字符串的流变量。 注意：流变量的前缀必须为“private”。例如， |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
指定在生成使用对称 (HS*) 算法（HS256、HS384 或 HS512 之一）的 JWS 时使用的密钥。
该元素是可选的。但是，您必须仅添加 <PrivateKey> 或 <SecretKey> 元素之一。生成使用非对称算法（RS*、PS* 或 ES* 之一）签名的 JWS 时使用 <PrivateKey> 元素，生成使用对称算法（HS* 等算法）签名的 JWS 时使用 <SecretKey> 元素。
<SecretKey> 的子项
下表提供了 <SecretKey> 的子元素和属性的说明：
| 子女 | Presence | 说明 |
|---|---|---|
| 编码（属性） | 可选 | 指定在引用的变量中编码密钥的方式。默认情况下，如果不存在 <SecretKey encoding="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 在上面的示例中，由于编码为 |
| Id（元素） | 可选 | 密钥标识符。该值可以是任何字符串。您可以将该值指定为字面量文本值，也可以使用 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> 政策会在所生成 JWS 的标头中将此密钥标识符添加为 |
| Value（元素） | 必需 | 编码密钥。指定用于为载荷签名的密钥。使用 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 字节，HS384 为 48 字节，HS512 则为 64 字节。使用较低强度的密钥会导致运行时错误。 |
<Type>
<Type>type-string-here</Type>
可选元素，唯一允许的值是 Signed，用于指定政策生成签名 JWS。提供的 <Type> 仅用于匹配 GenerateJWT 和 VerifyJWT 政策的相应元素（可以接受值 Signed 或 Encrypted）。
| 默认 | 不适用 |
| Presence | 可选 |
| 类型 | 字符串 |
| 有效值 | Signed |
流变量
生成 JWS 政策不设置流变量。
错误参考信息
本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 发生的条件 |
|---|---|---|
steps.jws.GenerationFailed |
401 |
该政策无法生成 JWS。 |
steps.jws.InsufficientKeyLength |
401 |
HS256 算法的密钥小于 32 个字节 |
steps.jws.InvalidClaim |
401 |
用于缺失声明或声明不匹配，或者缺少标题或标头不匹配的情况。 |
steps.jws.InvalidCurve |
401 |
密钥指定的曲线对椭圆曲线算法无效。 |
steps.jws.InvalidJsonFormat |
401 |
可在 JWS 标头中找到无效的 JSON。 |
steps.jws.InvalidPayload |
401 |
JWS 负载无效。 |
steps.jws.InvalidSignature |
401 |
省略 <DetachedContent> 并且 JWS 具有分离的内容负载。 |
steps.jws.KeyIdMissing |
401 |
验证政策使用 JWKS 作为公钥的来源，但已签名的 JWS 不包含标头中的 kid 属性。 |
steps.jws.KeyParsingFailed |
401 |
无法通过给定密钥信息解析公钥。 |
steps.jws.MissingPayload |
401 |
JWS 负载缺失。 |
steps.jws.NoAlgorithmFoundInHeader |
401 |
在 JWS 省略算法标头时发生。 |
steps.jws.SigningFailed |
401 |
在 GenerateJWS 中，密钥小于 HS384 或 HS512 算法的大小下限。 |
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>