[V5.0.1 或更高版本]仅限 DataPower Gateway生成 JWT (jwt-generate)

使用 IBM® API Connect 中的 生成 JWT 安全策略来生成 JSON Web 令牌 (JWT)。

限制： 生成 JWT 策略只能与 DataPower® Gateway 一起使用。

关于

JSON Web 令牌 (JWT) 以一种紧凑的 URL 安全方式来表示双方之间传输的声明。生成 JWT 策略支持您生成声明，并配置是要将它们用作为 JSON Web 签名 (JWS) 结构的有效内容，还是用作 JSON Web 加密 (JWE) 结构的纯文本。指定 JWS 和 JWE 的加密资料会生成含数字签名并且已加密的嵌套 JWT。随后会将 JWT 分配到 Authorization 头作为不记名令牌（缺省选项），或者分配到 JSON Web 令牌 (JWT) 属性中的运行时变量（如果已指定）。

您可以将此策略附加到以下 API 流：
  • REST
  • SOAP
注：
  • 对于算法类型 HS256、HS384 和 HS512，引用的加密对象必须为“共享密钥”。
  • 对于算法类型 RS256、RS384、RS512、ES256、ES384 和 ES512，引用的加密对象必须为“加密密钥（专用密钥）”。
  • 加密资料可通过 JSON Web 密钥 (JWK) 提供。
  • 如果指定了加密对象和 JWK，那么加密对象用于对 JWT 进行签名。

先决条件

以下先决条件适用：
  • IBM API Connect V5.0.1 或更高版本。
  • IBM DataPower V7.5（含“应用程序优化”(AO) 选项）。
  • 如果使用一个或多个加密对象，那么这些加密对象必须位于 DataPower 设备的 IBM API Connect 域中。加密对象必须引用“共享密钥”或者对 JWT 内容进行加密或签名所需的证书。
  • 如果使用 JSON Web 密钥 (JWK)，那么必须由运行时变量引用此密钥。

属性

下表列出了策略属性，指示属性是否为必需属性，指定输入的有效值和缺省值并指定值的数据类型。

表 1. 生成 JWT策略属性
属性标签 属性名称 必需 描述 数据类型
标题 title 否 策略的标题。

缺省值为 jwt-generate。

 字符串
描述 description 否 对策略的描述。 字符串
JSON Web 令牌 (JWT) jwt 否 在其中放置生成的 JWT 的运行时变量。

缺省值为：generated.jwt。但如果未设置，那么生成的 JWT 会写入 Authorization 头作为不记名令牌。

 字符串
JWT 标识声明 jti-claim 否 指示是否应将 JWT 标识 (jti) 声明添加到 JWT 中。

如果选中此项，那么该属性设置为 true，并且会生成一个 UUID 并设置为 JTI 声明值。

 布尔值
发出者声明 iss-claim 是 可从中检索发出者 (iss) 声明字符串的运行时变量。此声明表示发出 JWT 的主体。

缺省值为：iss.claim

 字符串
主题声明 sub-claim 否 可从中检索主题 (sub) 声明字符串的运行时变量。 字符串
受众声明 aud-claim 否 可从中检索受众 (aud) 声明字符串的运行时变量。可通过逗号分隔的字符串设置多个变量。 字符串
有效期 exp-claim 是 添加到当前日期和时间上的时间长度（以秒为单位），JWT 在这段时间内被视为有效。

缺省值为 3600。

 整数
专用声明 private-claims 否 可从中检索有效 JSON 声明集的运行时变量。这些声明将添加到先前指定的任何声明集中。 字符串
签名 JWK 变量名称 jws-jwk 否 包含用于对 JWT 进行签名的 JWK 的运行时变量。1 字符串
加密算法 jws-alg 否 要使用的加密算法。有效值为：
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512
  • 无
 字符串
签名加密对象 jws-crypto 否 要用于对 JWT 进行签名的加密对象。1 字符串
加密算法 jwe-enc 否 要使用的加密算法。有效值为：
  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
 字符串
加密 JWK 变量名称 jwe-jwk 否 运行时变量，包含用于加密 JWT 的 JWK。 字符串
密钥加密算法 jwe-alg 否 要使用的密钥加密算法。有效值为：
  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • dir
  • A128KW
  • A192KW
  • A256KW
 字符串
进行加密的加密对象 jwe-crypto 否 要用于加密声明的加密对象。 字符串

示例

- jwt-generate:
    title: jwt-generate
    iss-claim: iss.claim
    exp-claim: 3600
    jwt: generated.jwt
    jti-claim: true
    sub-claim: sub.claim
    aud-claim: aud.claim
    private-claims: private.claims
    jws-jwk: jws.jwk
    jws-alg: HS256
    jws-crypto: jwsCryptoObjectName
    jwe-enc: A128CBC-HS256
    jwe-jwk: jwe.jwk
    jwe-alg: A128KW
    jwe-crypto: jweCryptoObjectName

错误

在执行策略时可能抛出以下错误：
  • RuntimeError - 捕获策略执行期间发生的所有错误的一般错误。捕获失败时，从底层 JOSE 模块接收到的详细错误消息会作为错误消息写入缺省系统日志。此详细错误消息还会分配到运行时变量 jwt-generate.error-message，以便通过捕获来检索此消息。
如果未配置捕获，那么捕获失败时，生成 JWT 策略会返回 HTTP 代码 500 Invalid-JWT-Generate 故障。可在系统日志中找到来自底层 JOSE 模块的详细错误消息。
相关信息:
JSON Web 令牌简介
1 JWK 和加密对象都是提供对 JWT 进行签名所需加密数据的有效途径。但如果同时指定这两种数据类型，那么仅使用加密对象。
时间戳记图标 上次更新时间：2017-10-24