GenerateJWT 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

通过一组可配置的声明生成签名 JWT 或加密 JWT。那么，JWT 可返回到客户端，传输到后端目标，或以其他方式使用。如需查看详细介绍，请参阅 JWS 和 JWT 政策概览。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

方式

政策是生成签名 JWT 还是加密 JWT 取决于您是使用哪种元素来指定用于生成 JWT 的算法：

如果您使用 <Algorithm> 元素，则政策会生成签名 JWT。
如果您使用 <Algorithms> 元素，则政策会生成加密 JWT。

视频

观看视频短片，了解如何生成已签名的 JWT。

生成签名 JWT

本部分介绍如何生成签名 JWT。对于签名 JWT，请使用 <Algorithm> 元素指定用于为密钥签名的算法。

签名 JWT 的示例

以下示例说明了如何生成签名 JWT。

HS256 算法

此政策示例会生成新的 JWT 并使用 HS256 算法为其签名。HS256 依赖共享密钥来签署和验证签名。

当触发此政策操作时，Apigee 会编码 JWT 标头和载荷，然后以数字签署 JWT。请观看上方视频，了解完整示例（包括如何向政策发出请求）。

此处的政策配置将创建 JWT，其中包含一组标准声明（由 JWT 规范定义），其中包括 1 小时的过期时间以及附加声明。您可以根据需要添加任意数量的其他声明。请参阅“元素参考”，详细了解此示例政策中每个元素的要求和选项。

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Type>Signed</Type>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

生成的 JWT 将具有此标头 …

{
  "typ" : "JWT",
  "alg" : "HS256",
  "kid" : "1918290"
}

… 并且将包含内容如下的载荷：

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-JWT-policy-test",
  "aud" : "fans",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

iat、exp 和 jti 声明的值会有所不同。

RS256 算法

注意：使用此同一示例为 PS256 或 ES256 算法生成 JWT。只需将 <Algorithm>RS256</Algorithm> 的值更改为 PS256 或 ES256 即可。对于 ES256，您还必须指定与算法兼容的密钥。如需详细了解密钥要求，请参阅签名加密算法简介。

此政策示例会生成新的 JWT 并使用 RS256 算法为其签名。生成 RS256 签名依赖于 RSA 私钥，此私钥必须以 PEM 编码格式提供，并且可以通过密码对其进行加密。请观看上方视频，了解完整示例（包括如何向政策发出请求）。

当触发此政策操作时，Apigee 会对 JWT（包括声明）进行编码和数字签名。如需了解 JWT 各部分及其加密和签名的方式，请参阅 RFC7519。

<GenerateJWT name="JWT-Generate-RS256">
    <Type>Signed</Type>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

上述示例使用 <Algorithm> 元素，因此它们会生成签名 JWT。<PrivateKey> 元素指定用于为 JWT 签名的加密密钥。此外，还有一些其他的密钥元素。使用哪种密钥元素取决于通过 <Algorithm> 的值指定的算法，如下一部分所述。

为签名 JWT 设置密钥元素

使用以下元素中的一种元素来指定用于生成签名 JWT 的密钥：

<SecretKey>
<PrivateKey>

使用哪种元素取决于所选算法，如下表所示：

算法	密钥元素
HS{256/384/512}^*	<SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey>
RS/PS/ES{256/384/512}^*	<PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey>

算法

密钥元素

HS{256/384/512}^*

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id ref="secretkey-id">key-1918290</Id>
</SecretKey>

RS/PS/ES{256/384/512}^*

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="privatekey-id">key-1918290</Id>
</PrivateKey>

在上面的示例中，<Password> 和 <Id> 元素是可选字段。

如需详细了解密钥要求，请参阅签名加密算法简介。

生成加密 JWT

本部分介绍如何生成加密 JWT。对于加密 JWT，请使用 <Algorithms> 元素指定用于为密钥和内容签名的算法。

加密 JWT 的示例

以下示例展示了如何生成加密 JWT。该示例使用 <Algorithms> 元素，因此会生成加密 JWT。

RSA-OAEP-256

在下面的示例中：

密钥使用 RSA-OAEP-256 算法进行加密。
内容使用 A128GCM 算法进行加密。

<PublicKey> 元素指定用于加密密钥的密钥。

<GenerateJWT name="gjwt-1">
  <Type>Encrypted</Type>
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <PublicKey>
    <Value ref="rsa_publickey"/>
  </PublicKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

A128KW

在下面的示例中：

密钥使用 A128KW 算法进行加密。
内容使用 A128GCM 算法进行加密。

<SecretKey> 元素指定用于加密密钥的密钥。

<GenerateJWT name='gjwt-2'>
  <Algorithms>
    <Key>A128KW</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey>
    <Value ref='private.secretkey'/>
  </SecretKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

为加密 JWT 设置密钥元素

如果您想生成加密 JWT，请使用以下元素中的一种元素来为 GenerateJWT 指定加密密钥：

<PublicKey>
<SecretKey>
<PasswordKey>
<DirectKey>

使用哪种元素取决于所选密钥加密算法，如下表所示：

密钥加密算法	密钥元素
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> 注意：密钥必须解析为 RSA 公钥。
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> <Value ref="ec_publickey"/> </PublicKey> 注意：密钥必须解析为椭圆曲线公钥。
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey>
dir	<DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16\|hex\|base64\|base64url" ref="private.directkey"/> </DirectKey>

如需详细了解密钥要求，请参阅签名加密算法简介。

生成 JWT 的元素参考

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

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

适用于顶级元素的属性

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

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

属性	说明	默认	Presence
name	政策的内部名称。您可以在名称中使用的字符仅限于 `A-Z0-9._\-$ %`。但是，Apigee 界面会实施其他限制，例如自动移除非字母数字字符。（可选）使用 `<displayname></displayname>` 元素在 Apigee 界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
continueOnError	设置为 `false` 可在政策失败时返回错误。对于大多数政策来说，这一行为符合预期。设置为 `true`，即使在政策失败后，仍可以继续实施流执行。	false	可选
已启用	设置为 `true` 可实施政策。设置为 `false` 可“关闭”政策。即使政策仍附加到某个流，也不会实施该政策。	true	可选
async	此属性已弃用。	false	已弃用

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

指定用于为令牌签名的加密算法。使用 <Algorithm> 元素生成签名 JWT。

注意：您只能使用 <Algorithm> 和 <Algorithms> 这两种元素中的一种元素。

默认	不适用
Presence	可选。需要提供 `<Algorithm>` 或 `<Algorithms>` 中的一个。
类型	字符串
有效值	HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

指定用于加密密钥和内容的加密算法。使用 <Algorithms> 元素生成加密 JWT。

注意：您只能使用 <Algorithm> 和 <Algorithms> 这两种元素中的一种元素。

默认	不适用
可选。需要提供 `<Algorithm>` 或 `<Algorithms>` 中的一个。	必需
类型	字符串

`<Algorithms>` 的子元素

下表提供了 <Algorithms> 的子元素的简要说明：

子元素	是否必需？	说明
`<Key>`	必需	指定密钥的加密算法。
`<Content>`	必需	指定内容的加密算法。

密钥加密算法

下表列出了可用的密钥加密算法。

`<Key>` 的值（密钥加密算法）	需要提供密钥元素
dir	`<DirectKey>`
RSA-OAEP-256	`<PublicKey>`（必须解析为 RSA 公钥）
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	`<SecretKey>`
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	`<PasswordKey>`
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	`<PublicKey>`（必须解析为椭圆曲线公钥）

请参阅生成加密 JWT 部分，该部分的示例使用的密钥加密算法是 RSA-OAEP-256，因此需要用到 <PublicKey> 元素，并且该元素的值需解析为 RSA 公钥。

内容加密算法

以下算法（基于 AES 的对称算法）均可用于内容加密：

A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
A128GCM
A192GCM
A256GCM

如需详细了解所有这些算法，请参阅 RFC7518。

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

该政策会生成一个 JWT，其中包含设置为特定值的 aud 声明。此声明标识 JWT 的目标接收者。这是 RFC7519 中所述的一种已注册声明。

默认	不适用
Presence	可选
类型	数组（以英文逗号分隔的值列表）
有效值	任何标识受众群体的内容。

<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 载荷中指定其他声明名称/值对。您可以将声明显式指定为字符串、数字、布尔值、映射或数组。映射只是一组名称/值对。

type=map 时，<Claim> 元素支持名为消息模板的动态字符串替换功能。

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

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

名称 -（必需）声明的名称。
注意：请勿在该元素中使用任何已注册声明名称。RFC7519 中列明了已注册声明。它们包括：“iss”“sub”“aud”“iat”“exp”“nbf”和“jti”。
ref -（可选）流变量的名称。如果存在，该政策将使用此变量的值作为声明。如果同时指定了 ref 属性值和明确的声明值，则明确的值则为默认值，并且在引用的流变量未解析的情况下，将使用该值。
类型 -（可选）以下任一项：字符串（默认）、数字、布尔值或映射
数组 -（可选）设置为 true 可指示值是否为类型数组。默认值：false。

添加 <Claim> 元素时，系统会在配置政策时静态设置声明名称。或者，您可以传递 JSON 对象来指定声明名称。由于 JSON 对象是作为变量传递的，因此生成的 JWT 中的声明名称是在运行时确定的。

例如：

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

生成的 JWT 包含 JSON 对象中的所有声明。

务必注意在 Claim 元素中使用变量引用和显式声明值时的以下行为：

在以下情况下，Apigee 不会生成声明：

如果存在变量引用，但未解析，并且
如果您未指定显式值（默认值），并且
如果 IgnoreUnresolvedVariables 政策属性为 true。

如果 IgnoreUnresolvedVariables 为 false，则 Apigee 会在上述条件下抛出错误。

在以下情况下，Apigee 将生成声明：

如果存在变量引用，但未解析，并且
如果您指定了显式值（默认值），并且
如果 IgnoreUnresolvedVariables 为 true 或 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 的标头中放置额外的声明名称/值对。

type=map 时，<Claim> 元素支持名为消息模板的动态字符串替换功能。

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

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

名称 -（必需）声明的名称。
注意：请勿在该元素中使用任何已注册声明名称。RFC7519 中列明了已注册声明。它们包括：“iss”“sub”“aud”“iat”“exp”“nbf”和“jti”。
ref -（可选）流变量的名称。如果存在，该政策将使用此变量的值作为声明。如果同时指定了 ref 属性值和明确的声明值，则明确的值则为默认值，并且在引用的流变量未解析的情况下，将使用该值。
类型 -（可选）以下任一项：字符串（默认）、数字、布尔值或映射
数组 -（可选）设置为 true 可指示值是否为类型数组。默认值：false。

<Compress>

<Compress>true</Compress>

指定是否在加密前压缩文本。此元素仅在生成加密 JWT 时有效。

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

根据相关规范要求，验证方必须检查 crit 标头并验证是否每个标头都是合理的。例如，VerifyJWT 政策便会检查 crit 标头。对于 crit 标头中列出的每一项，系统都会检查 VerifyJWT 政策的 <KnownHeaders> 元素是否也列出该标头。VerifyJWT 政策在 crit 中找到的任何未在 <KnownHeaders> 中列出的标头都会导致 VerifyJWT 政策失败。

注意：<CriticalHeaders> 实际上并不会将标头添加到 JWT。它仅定义 crit 标头的内容。您可以使用 <AdditionalHeader/Claims> 添加标头。

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

<CustomClaims>

注意：目前，当您通过界面添加新的 GenerateJWT 政策时，系统会插入 CustomClaims 元素。该元素不起作用，忽略即可。请改用正确的元素，即 <AdditionalClaims>。界面将进行更新，以便稍后插入正确的元素。

<DirectKey>

<DirectKey>
  <Id>A12345</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

当加密算法为 dir（“直接加密”）时，指定用于加密 JWT 的直接密钥。

`<DirectKey>` 的子元素

下表提供了 <DirectKey> 的子元素的简要说明：

子元素	是否必需？	说明
ID	可选	键标识符
值	必需	使用 `ref` 属性指定对变量的引用。所引用变量的内容必须是字节数组的字符串编码，需采用 hex (base16)、base64 或 base64url 中的一种进行编码。

通过直接密钥加密，您可以直接提供一些字节来用作内容加密密钥 (CEK)。您必须以编码字符串形式指定字节数组。所需的字节数组长度取决于所选内容加密算法的强度。例如，对于 A256CBC-HS512，您必须提供长度恰好为 512 位（即 64 字节）的密钥。

变量 private.directkey 的内容必须是采用 hex (base16)、base64 或 base64url 中的一种进行编码的字符串。例如，下面便是一个采用十六进制编码的 32 字节密钥：

96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11

对于十六进制编码，可以使用空格但非必需，并且大小写字母均受支持（即 B7 等同于 b7）。

上面密钥的 base64url 编码等效项如下：

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

对于各种 base64* 变体，不支持使用空格，并且区分大小写。如果您未指定编码方式，则政策会假定采用 base64 编码。

下表介绍了所需的密钥长度：

内容加密算法	密钥长度要求
A128CBC-HS256	256 位（32 字节）
A192CBC-HS384	384 (48)
A256CBC-HS512	512 (64)
A128GCM	128 (16)
A192GCM	192 (24)
A256GCM	256 (32)

注意：通过 <DirectKey> 元素提供的内容加密密钥的长度必须恰好与指定内容加密算法的长度一致。对于 dir 以外的任何密钥加密算法，政策都会生成具有相应正确长度的随机 CEK；但对于 dir，需要通过配置明确提供具有相应正确长度的密钥。

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

or:

<ExpiresIn ref='time-value-here'/>

指定 JWT 的生命周期，以毫秒、秒、分钟、小时或天为单位。使用 XML 元素或 ref 属性指定到期时间，但不能同时使用这两者。

默认	`N/A`
Presence	可选
类型	整数
有效值	值或对包含该值的流变量的引用。时间单位可以按如下方式指定： ms = 毫秒（默认） s = 秒 m = 分钟 h = 小时 d = 天例如，`ExpiresIn`=10d 等同于 864000s 的 `ExpiresIn`。

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

使用特定的 jti 声明生成 JWT。当文本值和 ref 属性都为空时，该政策将生成一个包含随机 UUID 的 jti。JWT ID (jti) 声明是 JWT 的唯一标识符。如需详细了解 jti，请参阅 RFC7519。

默认	不适用
Presence	可选
类型	字符串或引用。
有效值	字符串或包含 ID 的流变量的名称。

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

默认	False
Presence	可选
类型	布尔值
有效值	true 或 false

<Issuer>

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

该政策会生成一个 JWT，其中包含名为 iss 的声明，并将值设置为指定值。用于识别 JWT 颁发者的声明。这是 RFC7519 中所述的一组已注册声明组。

默认	不适用
Presence	可选
类型	字符串或引用
有效值	不限

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

指定令牌生效的时间。令牌在指定时间之前无效。您可以指定绝对时间值，也可以指定一个相对于令牌生成时间的时间。

默认	不适用
Presence	可选
类型	字符串
有效值	请参阅下文。

绝对时间值的 NotBefore 元素的有效时间值

名称	格式	示例
可排序	`yyyy-MM-dd'T'HH:mm:ss.SSSZ`	2017-08-14T11:00:21.269-0700
RFC 1123	`EEE, dd MMM yyyy HH:mm:ss zzz`	美国太平洋夏令时 2017 年 8 月 14 日星期一 11:00:21
RFC 850	`EEEE, dd-MMM-yy HH:mm:ss zzz`	美国太平洋夏令时 2017 年 8 月 14 日 11:00:21
ANCI-C	`EEE MMM d HH:mm:ss yyyy`	2017 年 8 月 14 日星期一 11:00:21

对于相对时间值，指定整数和时间段，例如：

10s
60m
12 小时

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

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

默认	`jwt.POLICYNAME.generated_jwt`
Presence	可选
类型	字符串（流变量名称）

<PasswordKey>

<PasswordKey>
  <Id>abcdefg</Id>
  <Value ref="private.password"/>
  <SaltLength>8</SaltLength>
  <PBKDF2Iterations>10000</PBKDF2>
</PasswordKey>

当加密算法为以下某一项时，指定用于加密 JWT 的密钥：

PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW

对于其中每个密钥算法，您都必须通过 <Value ref="private.password"/> 元素中的 private.password 变量提供可以从中提取密钥加密密钥的密码。

`<PasswordKey>` 的子元素

下表提供了 <PasswordKey> 的子元素的简要说明：

子元素	Presence	说明
ID	可选	键标识符
值	必需	指定用于生成密钥加密密钥的密码。使用 `ref` 属性并指定变量，例如 `private.password`。
SaltLength	可选	盐长度。默认值：8 字节。
PBKDF2Iterations	可选	PBKDF2 迭代次数：默认值：10000。

<PrivateKey>

<PrivateKey>
  <Id ref="privatekey-id"/>
  <Value ref="private.pem-encoded-privatekey"/>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

指定要在生成签名 JWT 时使用的私钥，其中 Algorithm 是 RSA 或椭圆曲线 (EC) 变体（即 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一）。

`<PrivateKey>` 的子元素

下表提供了 <PrivateKey> 的子元素相关的说明：

子元素 Presence 说明

可选

子元素	Presence	说明
ID	可选	密钥标识符。该值可以是任何字符串。您可以将该值指定为字面量文本值，也可以使用 `ref` 属性通过变量引用间接指定该值。政策会在所生成 JWT 的标头中将此密钥标识符添加为 `kid` 声明。
值	必需	采用 PEM 编码的私钥。指定用于为载荷签名的私钥。使用 `ref` 属性并指定变量，例如 `private.private-key`。如果 `<Algorithm>` 元素包含 RSA 变体（RS256/RS384/RS512 或 PS256/PS384/PS512 之一），则您必须提供已编码的 RSA 私钥。如果 `<Algorithm>` 元素包含 EC 变体（ES256/ES384/ES512 之一），则您必须为相应的曲线提供椭圆曲线私钥。
密码	可选	如有必要，指定政策应该用来解密私钥的密码。使用 `ref` 属性通过流变量传递密码。注意：您必须指定流变量。如果政策配置中的密码采用明文形式指定，Apigee 会拒绝该配置并将其视为无效配置。流变量的前缀必须为“private”。例如 `private.mypassword`

密钥标识符。该值可以是任何字符串。您可以将该值指定为字面量文本值，也可以使用 ref 属性通过变量引用间接指定该值。

政策会在所生成 JWT 的标头中将此密钥标识符添加为 kid 声明。

值

必需

采用 PEM 编码的私钥。指定用于为载荷签名的私钥。使用 ref 属性并指定变量，例如 private.private-key。

如果 <Algorithm> 元素包含 RSA 变体（RS256/RS384/RS512 或 PS256/PS384/PS512 之一），则您必须提供已编码的 RSA 私钥。如果 <Algorithm> 元素包含 EC 变体（ES256/ES384/ES512 之一），则您必须为相应的曲线提供椭圆曲线私钥。

密码

可选

如有必要，指定政策应该用来解密私钥的密码。使用 ref 属性通过流变量传递密码。

注意：您必须指定流变量。如果政策配置中的密码采用明文形式指定，Apigee 会拒绝该配置并将其视为无效配置。流变量的前缀必须为“private”。例如 private.mypassword

<PublicKey>

<PublicKey>
  <!-- specify exactly one of the following -->
  <Value ref="variable-containing-encoded-publickey"/>
  <Value>PEM encoded public key</Value>
  <Certificate ref="variable-containing-encoded-x509-certificate"/>
  <Certificate>PEM encoded X509 certificate</Certificate>
  <JWKS>jwks-content</JWKS>
  <JWKS ref="variable-containing-jwks-content"/>
  <JWKS uri="variable-containing-jwks-content"/>
  <JWKS uriRef="variable-containing-uri"/>
</PublicKey>

指定要在生成加密 JWT 时使用的公钥，其中 Key 算法是 RSA 或椭圆曲线 (EC) 变体（即 RSA-OAEP-256、ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW 或 ECDH-ES+A256KW 之一）。

`<PublicKey>` 的子元素

仅提供 Value、Certificate 或 JWKS 中的一个。如果您指定 JWKS，则还必须指定 Id。下表提供了 <PublicKey> 的这些子元素相关的说明：

子元素	说明
值	采用 PEM 编码的公钥。指定政策应该用来加密内容加密密钥的公钥。您可以直接用字面量指定密钥，也可以通过变量引用间接指定密钥。 <PublicKey> <Value ref="public.publickey"/> </PublicKey> 或 <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> 如果您使用 RSA-OAEP-256 算法，则编码公钥必须表示 RSA 密钥；如果您使用 EC 算法，则应为相应曲线的 EC 密钥。
证书	封装了公钥的 PEM 编码的 X.509 证书。Apigee 将从证书中提取公钥，然后使用该密钥加密内容加密密钥。您可以直接用字面量指定证书，也可以通过变量引用间接指定证书。 <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> 或 <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> 如果您使用 RSA-OAEP-256 算法，则编码公钥必须表示 RSA 密钥；如果您使用 EC 算法，则应为相应曲线的 EC 密钥。注意：Apigee 不会验证您提供的证书上的有效日期，Apigee 也不会验证证书上的信任链。Apigee 会将您使用此元素指定的所有证书视为有效且可信的证书。
JWKS	JWKS 公钥来源。这是采用 IETF RFC 7517 - JSON Web 密钥 (JWK) 中所述格式的密钥的列表。您可以通过以下四种方式之一指定 JWKS：以文本值形式指定为字面量： <PublicKey> <JWKS>jwks-content-here</JWKS> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 使用 `ref` 属性通过流变量间接指定： <PublicKey> <JWKS ref="variable-containing-jwks-content"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 所引用变量应包含表示 JWKS 的字符串。使用 `uri` 属性通过静态 URI 间接指定： <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 使用 `uriRef` 属性通过动态确定的 URI 间接指定： <PublicKey> <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 在上述任何情况下，若在用于生成加密 JWT 的 GenerateJWT 中指定 `JWKS` 元素，则还必须同时指定 `PublicKey/Id` 元素。 <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey>
ID	表示密钥标识符的字符串。在运行时，Apigee 会从 JWKS 中检索 `kid` 字段与该值匹配的密钥。如果您在 GenerateJWT 中使用 `JWKS` 元素，则还需要指定 `Id` 元素。

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

SecretKey 元素是可选的。它指定要在生成使用对称 (HS*) 算法的签名 JWT 或生成使用对称 (AES) 算法加密密钥的加密 JWT 时使用的密钥。

`<SecretKey>` 的子项

下表提供了 <SecretKey> 的子元素和属性的说明：

子女 Presence 说明

编码（属性）

可选

子女	Presence	说明
编码（属性）	可选	指定在引用的变量中编码密钥的方式。默认情况下，如果不存在 `encoding` 属性，则密钥编码会作为 UTF-8 进行处理。属性的有效值包括：hex、base16、base64 或 base64url。编码值 hex 和 base16 是同义词。 <SecretKey encoding="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 在上面的示例中，当编码属性为 `hex` 且变量 `private.secretkey` 的内容为 `494c6f766541504973` 时，密钥会被解码为十六进制的 9 个字节 `49 4c 6f 76 65 41 50 49 73`。相反，当编码属性为 `base64` 且变量 `private.secretkey` 的内容为 `VGhpcy1pcy1hLXNlY3JldA` 时，密钥将被解码为十六进制的 16 个字节：`54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74`。注意：Apigee 强制执行最小密钥强度。如需了解详情，请参阅 `Value` 元素的文档。
Id（元素）	可选	密钥标识符。该值可以是任何字符串。您可以将该值指定为字面量文本值，也可以使用 `ref` 属性通过变量引用间接指定该值。 <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> 政策会在所生成 JWT 的标头中将此密钥标识符添加为 `kid` 声明。
Value（元素）	必需	编码密钥。指定用于为载荷签名的密钥。使用 `ref` 属性通过变量（例如 `private.secret-key`）间接提供密钥。 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> 注意：变量名称必须包含 private 前缀，如以上示例所示。 Apigee 为 HS256/HS384/HS512 算法强制执行最小密钥强度。HS256 的最小密钥长度为 32 字节，HS384 为 48 字节，HS512 则为 64 字节。使用较低强度的密钥会导致运行时错误。

指定在引用的变量中编码密钥的方式。默认情况下，如果不存在 encoding 属性，则密钥编码会作为 UTF-8 进行处理。属性的有效值包括：hex、base16、base64 或 base64url。编码值 hex 和 base16 是同义词。

<SecretKey encoding="VALUE_HERE" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.secretkey"/>
</SecretKey>

在上面的示例中，当编码属性为 hex 且变量 private.secretkey 的内容为 494c6f766541504973 时，密钥会被解码为十六进制的 9 个字节 49 4c 6f 76 65 41 50 49 73。相反，当编码属性为 base64 且变量 private.secretkey 的内容为 VGhpcy1pcy1hLXNlY3JldA 时，密钥将被解码为十六进制的 16 个字节：54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74。

注意：Apigee 强制执行最小密钥强度。如需了解详情，请参阅 Value 元素的文档。

Id（元素）

可选

密钥标识符。该值可以是任何字符串。您可以将该值指定为字面量文本值，也可以使用 ref 属性通过变量引用间接指定该值。

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

政策会在所生成 JWT 的标头中将此密钥标识符添加为 kid 声明。

Value（元素）

必需

编码密钥。指定用于为载荷签名的密钥。使用 ref 属性通过变量（例如 private.secret-key）间接提供密钥。

<SecretKey>
 <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

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

<Subject>

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

或

<Subject ref="flow_variable" />

例如：

<Subject ref="apigee.developer.email"/>

该政策会生成一个 JWT，其中包含设置为指定值的 sub 声明。此声明可以标识或发出关于 JWT 主题的声明。这是 IETF RFC 7519 中包含的其中一组标准声明。

默认	不适用
Presence	可选
类型	字符串
有效值	唯一标识主题的任何值或引用值的流变量。

<Type>

<Type>type-string-here</Type>

描述政策是生成签名 JWT 还是加密 JWT。<Type> 元素是可选字段；您可以用它来说明配置的政策是生成签名 JWT 还是加密 JWT。

如果设置了 <Type> 元素：
- 如果 <Type> 的值为 Signed，则政策会生成签名 JWT，并且必须设置 <Algorithm> 元素。
- 如果 <Type> 的值为 Encrypted，则政策会生成加密 JWT，并且必须设置 <Algorithms> 元素。
如果未设置 <Type> 元素：
- 如果设置了 <Algorithm> 元素，则政策假定 <Type> 为 Signed。
- 如果设置了 <Algorithms> 元素，则政策假定 <Type> 为 Encrypted。
如果 <Algorithm> 和 <Algorithms> 均未设置，则配置无效。

默认	不适用
Presence	可选
类型	字符串
有效值	`Signed` 或 `Encrypted`。

流变量

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

错误参考信息

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

运行时错误

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

故障代码	HTTP 状态	发生的条件
`steps.jwt.AlgorithmInTokenNotPresentInConfiguration`	`401`	验证政策包含多个算法时发生。
`steps.jwt.AlgorithmMismatch`	`401`	生成政策中指定的算法与验证政策中要求的算法不匹配。指定的算法必须匹配。
`steps.jwt.EncryptionFailed`	`401`	创建加密 JWT 失败且原因不明
`steps.jwt.FailedToDecode`	`401`	该政策无法解码 JWT。JWT 可能已损坏。
`steps.jwt.GenerationFailed`	`401`	该政策无法生成 JWT。
`steps.jwt.InsufficientKeyLength`	`401`	HS256 算法的密钥小于 32 个字节，HS386 算法的密钥少于 48 个字节，HS512 算法的密钥少于 64 个字节。
`steps.jwt.InvalidClaim`	`401`	用于缺失声明或声明不匹配，或者缺少标题或标头不匹配的情况。
`steps.jwt.InvalidConfiguration`	`401`	同时存在 `<Algorithm>` 和 `<Algorithms>` 元素。
`steps.jwt.InvalidCurve`	`401`	密钥指定的曲线对椭圆曲线算法无效。
`steps.jwt.InvalidJsonFormat`	`401`	标头或载荷中存在无效的 JSON。
`steps.jwt.InvalidPasswordKey`	`401`	指定的密钥不符合要求。
`steps.jwt.InvalidPrivateKey`	`401`	指定的密钥不符合要求。
`steps.jwt.InvalidPublicKey`	`401`	指定的密钥不符合要求。
`steps.jwt.InvalidSecretKey`	`401`	指定的密钥不符合要求。
`steps.jwt.InvalidToken`	`401`	当 JWT 签名验证失败时，会发生此错误。
`steps.jwt.JwtAudienceMismatch`	`401`	目标对象声明未通过令牌验证。
`steps.jwt.JwtIssuerMismatch`	`401`	颁发者声明未通过令牌验证。
`steps.jwt.JwtSubjectMismatch`	`401`	主题声明未通过令牌验证。
`steps.jwt.KeyIdMissing`	`401`	验证政策使用 JWKS 作为公钥的来源，但已签名的 JWT 在标头中不包含的 `kid` 属性。
`steps.jwt.KeyParsingFailed`	`401`	无法通过给定密钥信息解析公钥。
`steps.jwt.NoAlgorithmFoundInHeader`	`401`	JWT 不包含算法标头时发生。
`steps.jwt.NoMatchingPublicKey`	`401`	验证政策使用 JWKS 作为公钥的来源，但已签名的 JWT 中的 `kid` 未列在 JWKS 中。
`steps.jwt.SigningFailed`	`401`	在 `GenerateJWT` 中，HS384 或 HS512 算法的密钥大小小于下限。
`steps.jwt.TokenExpired`	`401`	该政策尝试验证过期的令牌。
`steps.jwt.TokenNotYetValid`	`401`	令牌尚未生效。
`steps.jwt.UnhandledCriticalHeader`	`401`	验证 JWT 政策在 `crit` 标头中发现的标头未在 `KnownHeaders` 中列出。
`steps.jwt.UnknownException`	`401`	发生未知异常。
`steps.jwt.WrongKeyType`	`401`	指定的密钥类型不正确。例如，为椭圆曲线算法指定 RSA 密钥，或为 RSA 算法指定了曲线密钥。

部署错误

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

错误名称	原因	修复
`InvalidNameForAdditionalClaim`	如果 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中使用的声明是以下注册名称之一，部署将失败：`kid`、`iss`、`sub`、`aud`、`iat`、`exp`、`nbf`、`jti`。
`InvalidTypeForAdditionalClaim`	如果 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中使用的声明不是 `string`、`number`、`boolean` 或 `map` 之一，部署将失败。
`MissingNameForAdditionalClaim`	如果未在 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中指定声明的名称，部署将失败。
`InvalidNameForAdditionalHeader`	当 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中使用的声明的名称为 `alg` 或 `typ` 时会发生此错误。
`InvalidTypeForAdditionalHeader`	如果 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中使用的声明类型不是 `string`、`number`、`boolean` 或 `map` 之一，部署将失败。
`InvalidValueOfArrayAttribute`	当 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中数组特性的值未设置为 `true` 或 `false` 时会发生此错误。
`InvalidConfigurationForActionAndAlgorithm`	如果 `<PrivateKey>` 元素与 HS 系列算法搭配使用，或者 `<SecretKey>` 元素与 RSA Family 算法搭配使用，部署将失败。
`InvalidValueForElement`	如果 `<Algorithm>` 元素中指定的值不受支持，部署将失败。
`MissingConfigurationElement`	如果 `<PrivateKey>` 元素未与 RSA 系列算法搭配使用，或者 `<SecretKey>` 元素未与 HS 系列算法搭配使用，则会发生此错误。
`InvalidKeyConfiguration`	如果未在 `<PrivateKey>` 或 `<SecretKey>` 元素中定义子元素 `<Value>`，部署将失败。
`EmptyElementForKeyConfiguration`	如果 `<PrivateKey>` 或 `<SecretKey>` 元素的子元素 `<Value>` 的 ref 特性为空或未指定，部署将失败。
`InvalidVariableNameForSecret`	如果在 `<PrivateKey>` 或 `<SecretKey>` 元素的子元素 `<Value>` 的 ref 特性中指定的流变量名称不包含专用前缀 `(private.)`，则会出现此错误。
`InvalidSecretInConfig`	如果 `<PrivateKey>` 或 `<SecretKey>` 元素的子元素 `<Value>` 不包含专用前缀 `(private.)`，则会出现此错误。
`InvalidTimeFormat`	如果 `<NotBefore>` 元素中指定的值未使用支持的格式，则部署将失败。

故障变量

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

变量	地点	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name Matches "InvalidToken"`
`JWT.failed`	所有 JWT 政策都将在发生故障时设置同一变量。	`JWT.failed = true`

错误响应示例

JWT 政策故障代码

处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

故障规则示例

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>

GenerateJWT 政策

内容

方式

视频

生成签名 JWT

签名 JWT 的示例

HS256 算法

RS256 算法

为签名 JWT 设置密钥元素

生成加密 JWT

加密 JWT 的示例

RSA-OAEP-256

A128KW

为加密 JWT 设置密钥元素

生成 JWT 的元素参考

适用于顶级元素的属性

<DisplayName>

<Algorithm>

<Algorithms>

<Algorithms> 的子元素

密钥加密算法

内容加密算法

<Audience>

<AdditionalClaims/Claim>

<AdditionalHeaders/Claim>

<Compress>

<CriticalHeaders>

<CustomClaims>

<DirectKey>

<DirectKey> 的子元素

<ExpiresIn>

<Id>

<IgnoreUnresolvedVariables>

<Issuer>

<NotBefore>

<OutputVariable>

<PasswordKey>

<PasswordKey> 的子元素

<PrivateKey>

<PrivateKey> 的子元素

<PublicKey>

<PublicKey> 的子元素

<SecretKey>

<SecretKey> 的子项

<Subject>

<Type>

流变量

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

`<Algorithms>` 的子元素

`<DirectKey>` 的子元素

`<PasswordKey>` 的子元素

`<PrivateKey>` 的子元素

`<PublicKey>` 的子元素

`<SecretKey>` 的子项