GenerateJWS 政策

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

内容

生成一个已签名的 JWS，其中包含一组可配置的声明。随后，可将 JWS 返回到客户端、传输到后端目标或以其他方式使用。如需查看详细介绍，请参阅 JWS 和 JWT 政策概览。

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

视频通话

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

示例

生成使用 HS256 算法签名的已连接 JWS

此示例政策会生成已连接的 JWS 并使用 HS256 算法对其进行签名。HS256 依赖共享密钥来签署和验证签名。

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

header.payload.signature

将 <DetachContent> 设置为 true 可生成已分离的内容。如需详细了解 JWS 的结构和格式，请参阅 JWS/JWT 的组成部分。

使用 <Payload> 元素指定未编码的原始 JWS 载荷。在此示例中，变量包含载荷。触发此政策操作时，Edge 会对 JWS 标头和载荷进行编码，然后添加经过编码的签名，以便对 JWS 进行数字签名。

下面的政策配置根据变量 private.payload 中包含的载荷创建 JWS。

<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="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

生成使用 RS256 算法签名的已分离 JWS

此示例政策会生成一个已分离的 JWS 并使用 RS256 算法对其进行签名。生成 RS256 签名依赖于 RSA 私钥，此私钥必须以 PEM 编码格式提供。

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

header..signature

使用 <Payload> 元素指定未编码的原始 JWS 载荷。触发此政策时，Edge 会对 JWS 标头和载荷进行编码，然后使用它们生成经过编码的签名。但是，生成的 JWS 会忽略载荷。因此，您应使用 VerifyJWS 政策的 <DetachedContent> 元素将载荷传递给 VerifyJWS 政策。

<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="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-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>

<Password> 和 <Id> 元素是可选的。
*如需详细了解密钥要求，请参阅签名加密算法简介。

生成 JWS 的元素参考

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

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

适用于顶级元素的属性

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

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

特性 说明 默认 状态
name 政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。但是，Edge 管理界面会强制执行其他限制，例如自动移除非字母数字字符。

（可选）使用 <displayname></displayname> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
continueOnError 设置为 false 可在政策失败时返回错误。对于大多数政策来说，这一行为符合预期。

设置为 true，即使在政策失败后，仍可以继续实施流执行。

 false 选填
已启用 设为 true 即可强制执行此政策。

设置为 false 可“关闭”政策。即使政策仍附加到某个流，也不会实施该政策。

 true 选填
async 此属性已弃用。 false 已弃用

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

指定用于签署令牌的加密算法。

默认 不适用
状态 必需
类型 字符串
有效值 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 的标头中放置额外的声明名称/值对。

默认 不适用
状态 选填
有效值 要用于附加声明的任何值。您可以将声明显式指定为字符串、数字、布尔值、映射或数组。

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

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

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

将关键标头 crit 添加到 JWS。crit 标头是必须已知且 JWS 接收者可识别的标头名称数组。例如：

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

在运行时，VerifyJWS 政策会检查 crit 标头。对于 crit 标头中列出的每个标头，它会检查 VerifyJWS 政策的 <KnownHeaders> 元素也列出该标头。VerifyJWS 政策在 crit 中找到但未同时在 <KnownHeaders> 中列出的任何标头都会导致 VerifyJWS 政策失败。

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

<DetachContent>

<DetachContent>true|false</DetachContent>

指定是否生成具有已分离载荷的 JWS（<DetachContent>true</DetachContent>，否则为 <DetachContent>false</DetachContent>）。

如果指定 false，则在默认情况下，生成的 JWS 采用以下格式：

header.payload.signature

如果指定 true 以创建已分离载荷，则生成的 JWS 会省略载荷并采用以下格式：

header..signature

使用已分离载荷时，您应通过使用 VerifyJWS 政策的 <DetachedContent> 元素将未编码的原始载荷传递给 VerifyJWS 政策。

默认 false
状态 选填
类型 布尔值
有效值 true 或 false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

默认 false
状态 选填
类型 布尔值
有效值 true 或 false

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

指定此政策生成的 JWS 的放置位置。默认情况下，它会被放入流变量 jws.POLICYNAME.generated_jws。

默认 jws.POLICYNAME.generated_jws
状态 选填
类型 字符串（流变量名称）

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

指定未编码的原始 JWS 载荷。指定包含载荷的变量，或者指定一个字符串。

默认 不适用
状态 必需
类型 字符串、字节数组、流或未编码的 JWS 载荷的任何其他表示形式。

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

指定要包含在 JWS 标头中的密钥 ID (kid)。仅在算法是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一时使用。

默认 不适用
状态 选填
类型 字符串
有效值 流变量或字符串

<PrivateKey/Password>

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

根据需要指定政策应用来解密私钥的密码。使用 ref 属性在流变量中传递密钥。仅在算法是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一时使用。

默认 不适用
状态 选填
类型 字符串
有效值 流变量引用。

注意：您必须指定流变量。对于以明文形式指定密码的政策配置，边缘将拒绝该配置。流变量的前缀必须为“private”。例如 private.mypassword

<PrivateKey/Value>

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

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

默认 不适用
状态 使用 RS256 算法生成 JWS 所需。
类型 字符串
有效值 一个流变量，其中包含一个表示 PEM 编码的 RSA 私钥值的字符串。

注意：流变量的前缀必须为“private”。例如，private.mykey

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

指定要包含在使用 HMAC 算法签名的 JWS 的 JWS 标头中的密钥 ID (kid)。仅在算法是 HS256/HS384/HS512 之一时使用。

默认 不适用
状态 选填
类型 字符串
有效值 流变量或字符串

<SecretKey/Value>

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

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

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

默认 不适用
状态 HMAC 算法所需的属性。
类型 字符串
有效值 引用字符串的流变量

注意：如果使用流变量，则其前缀必须为“private”。例如：private.mysecret

流变量

生成 JWS 政策不设置流变量。

错误参考信息

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

运行时错误

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

故障代码 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。

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 其他可能的部署错误。

故障变量

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

变量 其中 示例
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>