[16.0.0.4 and later]

Liberty 中构建 JSON Web 令牌

您可以通过在服务器配置中配置 JWT 构建器元素并在应用程序中实现 com.ibm.websphere.security.jwt.JwtBuildercom.ibm.websphere.security.jwt.JwtToken API,以编程方式构建 JSON Web 令牌 (JWT) 令牌。

关于此任务

有关 JWT API 的信息,请参阅 JSON Web 令牌 Java 文档或随产品包含的 ${wlp.install.dir}/dev 目录中 API 文档。

过程

  1. [18.0.0.1 and later]从 JWT 令牌生成端点获取 JWT 令牌。
    1. 使用 jwt-1.0 功能部件的端点获取令牌,而无需进行编程。
    2. 如果请求中未包含凭证,请认证您的凭证以访问 https://<host>:<port>/jwt/api/ibm/<configId>/token 处的端点。 认证成功后,将在 JSON 表单中返回 MP-JWT 格式令牌。该令牌包含服务器的用户注册表中记录的用户及其所属的组。
    3. 通过 server.xml 文件中标识为 <configId> 的 JWTBuilder 元素的属性,设置其他令牌属性,例如签发者和到期时间。
    4. 如果未在 server.xml 文件中定义 JWTBuilder 元素,请使用 defaultJWT 作为 <configId> 标识。 请在 jwtBuilder - JWT 构建器 (jwtBuilder) 中查找可用的 JWT 构建器配置属性。
  2. 在 Liberty 中以编程方式构建 JSON Web 令牌。
  3. server.xml 文件中,添加 jwt-1.0 功能部件。
    <featureManager>
        <feature>jwt-1.0</feature>
        ...
    </featureManager>
  4. 通过修改 jwtBuilder 元素来配置 JWT 构建器。

    有关可配置的 jwtBuilder 属性的信息,请参阅 JWT 构建器 (jwtBuilder)

    添加 jwt-1.0 功能部件并保存更改时,Liberty 会添加以下缺省 jwtBuilder 元素。
    <jwtBuilder id="defaultJWT">
    </jwtBuilder>
    在此缺省配置中,将使用以下值:
    • exp 声明为令牌创建时间后 2 小时。您可以对 expiry 属性配置此值。
    • iss 声明设置为 https://<host_name>:<ssl_port>/jwt/defaultJWT。 针对 issuer 属性配置签发者。
    • JWT 通过在服务器的缺省密钥库中将 RS256 算法与专用密钥配合使用进行签名。此配置假设为服务器配置了缺省密钥库,且缺省密钥库包含单个专用密钥,此专用密钥可用于签名。如果针对 keyStoreRef 属性指定其他密钥库,那么会使用指定密钥库中的专用密钥。如果未配置 keyAlias 属性,并且密钥库仅包含一个专用密钥,那么将在签名中使用该专用密钥。

    您可以重新配置此缺省 jwtBuilder 元素,或创建一个或多个其他 jwtBuilder 元素。每个 jwtBuilder 元素必须将 URL 安全的唯一字符串指定为 id 属性。如果缺少标识,那么不会处理 jwtBuilder

    如果 JWT 令牌通过使用 RS256 算法进行签名,那么可通过设置 jwkEnabled="true",将 JWT 构建器配置为使用 JSON Web Key (JWK) 对 JWT 令牌进行签名。启用 JWK 时,JWT 构建器会动态生成密钥对,并使用专用密钥对 JWT 令牌进行签名。要验证签名,JWT 使用者可从 JWK API 检索密钥,此密钥具有以下格式:
    https://<host_name>:<ssl_port>/jwt/ibm/api/<jwtBuilder_configuration_id>/jwk
  5. 通过在应用程序中实现 com.ibm.websphere.security.jwt.JwtBuildercom.ibm.websphere.security.jwt.JwtToken API,以编程方式构建 JWT 令牌。

    有关更多信息,请参阅 JSON Web 令牌 Java 文档

    1. 创建 JwtBuilder 对象。
      如果未指定配置标识,那么对象绑定到缺省 jwtBuilder 配置。
      com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create();
      如果指定配置标识,那么对象绑定到具有指定标识的 jwtBuilder 配置。
      com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create("jwtBuilder_configuration_id");
    2. 修改令牌中的声明。
      • 添加或更新声明:jwtBuilder.claim("claim_name", "claim_value");
        jwtBuilder.claim("role", "monitor");
      • 删除声明:jwtBuilder.remove("claim_name");
        jwtBuilder.remove("role");
      • Liberty Federated User Registry 访存声明 jwtBuilder.fetch("attribute_name");

        此访存调用告知 JwtBuilder 对象在 Federated User Registry 中搜索通过 JWT 的 sub 声明标识的用户名。JwtBuilder 对象访存指定属性的值并根据此属性创建新声明。新声明的名称设置为属性名称,新声明的值设置为属性值。

      • 从现有 JWT 或 JSON 对象复制声明:jwtBuilder.claimFrom(JSON_or_JWT, "claim_name");
    3. 修改配置的签名算法和签名密钥。
      jwtBuilder.signWith("new_algorithm", new_key);
    4. 使用 com.ibm.websphere.security.jwt.JwtToken API 构建令牌。
      JwtToken jwtToken = jwtBuilder.buildJwt();
      String jwtTokenString = jwtToken.compact();

JSON Web 令牌 API 示例

以下示例创建新 JWT。
JwtBuilder jwtBuilder = JwtBuilder.create();
jwtBuilder.subject("tom@op.com").claim(Claims.AUDIENCE, "https://acme.com/rs").claim("iss","https://sso.com/ibm/op" ).claim("scope", "impersonator monitor").claim("uid", "hasys123haksiqws");
JwtToken goToken = jwtBuilder.buildJwt();
生成的 JWT 使用服务器的缺省专用密钥签名且包含以下声明。
{
"aud": "https://acme.com/rs",
"iss": "https://sso.com/ibm/op",
"iat": 1388440863, "exp": 1388444763,
"uid": "hasys123haksiqws",
"sub": "tom@op.com",
"scope": "impersonator monitor"
}
以下示例从其他 JWT goToken 构建 newToken JWT。
JwtToken newToken = JwtBuilder.create().claim(Claims.AUDIENCE, "https://acme.com/rs").claimFrom(goToken, "sub").claim(goToken, "uid").claim(goToken, "scope").buildJwt();

用于指示主题类型的图标 任务主题

文件名:twlp_sec_build_jwt.html