GenerateJWT 政策

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

内容

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

视频

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

示例

• 生成使用 HS256 算法签名的 JWT
• 生成使用 RS256 算法签名的 JWT

生成使用 HS256 算法签名的 JWT

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

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

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

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <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-edge-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-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

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

生成使用 RS256 算法签名的 JWT

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

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

<GenerateJWT name="JWT-Generate-RS256">
    <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-edge-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>

设置密钥元素

您用来指定用于生成 JWT 的密钥的元素取决于所选算法，如下表所示：

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

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

生成 JWT 的元素参考

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

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

适用于顶级元素的属性

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

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

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

• 名称 -（必需）声明的名称。
• 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 对象中的所有声明。

<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 的标头中放置额外的声明名称/值对。

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

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

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<CustomClaims>

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

<ExpiresIn>

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

指定 JWT 的生命周期，以毫秒、秒、分钟、小时或天为单位。

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

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

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

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

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

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

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

• 10s
• 60m
• 12 小时

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

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

<PrivateKey/Id>

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

or

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

指定要包含在 JWT 标头中的密钥 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 之一时使用。

<PrivateKey/Value>

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

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

<SecretKey/Id>

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

or

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

指定要包含在使用 HMAC 算法签名的 JWT 的 JWT 标头中的密钥 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 个字节。使用较低强度的密钥会导致运行时错误。

<Subject>

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

<Subject ref="flow_variable" />

例如：

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

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

流变量

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

错误参考信息

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

运行时错误

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

部署错误

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

故障变量

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

错误响应示例

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

故障规则示例

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