GenerateJWT 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

内容

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

视频

观看视频短片,了解如何生成已签名的 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."
}

iatexpjti 声明的值会有所不同。

生成使用 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 的密钥的元素取决于所选算法,如下表所示:

算法 密钥元素
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> 元素是可选的。

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

生成 JWT 的元素参考

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

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

适用于顶级元素的属性

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

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

属性 说明 默认 状态
name 政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。不过,Edge 管理界面会强制实施 限制,例如自动移除非字母数字字符。

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

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

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

false 可选
已启用 设置为 true 可实施政策。

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

true 可选
异步 此属性已弃用。 false 已弃用

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

默认 不适用
状态 必填
类型 字符串
有效值 HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

默认 不适用
状态 可选
Type 数组(以英文逗号分隔的值列表)
有效值 任何标识受众群体的内容。

<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 的生命周期,以毫秒、秒、分钟、小时或天为单位。

默认 N/A
状态 可选
类型 整数
有效值

值或对包含该值的流变量的引用。时间单位可以按如下方式指定:

  • 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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

默认 错误
状态 可选
类型 布尔值
有效值 true 或 false

<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 元素的有效时间值

名称 格式 示例
可排序 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
状态 可选
类型 字符串(流变量名称)

<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 之一时使用。

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

注意:您必须指定流变量。边缘将作为无效的 a 拒绝 其中密码以明文形式指定的政策配置。流变量的前缀必须为“private”。例如 private.mypassword

<PrivateKey/Value>

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

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

默认 不适用
状态 需要使用 RS256 算法生成 JWT。
Type 字符串
有效值 包含 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 算法签名的 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 个字节。使用较低强度的密钥会导致运行时错误。

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

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

<Subject>

<Subject>subject-string-here</Subject>
<Subject ref="flow_variable" />

例如:

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

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

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

流变量

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

错误参考信息

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

运行时错误

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

故障代码 HTTP 状态 发生的条件
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 验证政策包含多个算法时发生。
steps.jwt.AlgorithmMismatch 401 生成政策中指定的算法与验证政策中要求的算法不匹配。指定的算法必须匹配。
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.InvalidCurve 401 密钥指定的曲线对椭圆曲线算法无效。
steps.jwt.InvalidJsonFormat 401 标头或载荷中存在无效的 JSON。
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> 中使用的声明是以下注册名称之一,部署将失败:kidisssubaudiatexpnbfjti
InvalidTypeForAdditionalClaim 如果 <AdditionalClaims> 元素的子元素 <Claim> 中使用的声明不是 stringnumberbooleanmap 之一,部署将失败。
MissingNameForAdditionalClaim 如果未在 <AdditionalClaims> 元素的子元素 <Claim> 中指定声明的名称,部署将失败。
InvalidNameForAdditionalHeader <AdditionalClaims> 元素的子元素 <Claim> 中使用的声明的名称为 algtyp 时会发生此错误。
InvalidTypeForAdditionalHeader 如果 <AdditionalClaims> 元素的子元素 <Claim> 中使用的声明类型不是 stringnumberbooleanmap 之一,部署将失败。
InvalidValueOfArrayAttribute <AdditionalClaims> 元素的子元素 <Claim> 中数组特性的值未设置为 truefalse 时会发生此错误。
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 "TokenExpired"
JWT.failed 所有 JWT 政策都将在发生故障时设置同一变量。 JWT.failed = true

错误响应示例

JWT 政策故障代码

处理错误时,最佳做法是捕获错误响应的 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>