您可以通过在服务器配置中配置 JWT 构建器元素并在应用程序中实现 com.ibm.websphere.security.jwt.JwtBuilder 和 com.ibm.websphere.security.jwt.JwtToken API,以编程方式构建 JSON Web 令牌 (JWT) 令牌。
关于此任务
有关 JWT API 的信息,请参阅 JSON Web 令牌 Java 文档或随产品包含的 ${wlp.install.dir}/dev 目录中 API 文档。
过程
从 JWT 令牌生成端点获取 JWT 令牌。 - 使用 jwt-1.0 功能部件的端点获取令牌,而无需进行编程。
- 如果请求中未包含凭证,请认证您的凭证以访问
https://<host>:<port>/jwt/api/ibm/<configId>/token 处的端点。 认证成功后,将在 JSON 表单中返回 MP-JWT 格式令牌。该令牌包含服务器的用户注册表中记录的用户及其所属的组。
- 通过 server.xml 文件中标识为
<configId> 的 JWTBuilder 元素的属性,设置其他令牌属性,例如签发者和到期时间。
- 如果未在 server.xml 文件中定义 JWTBuilder 元素,请使用
defaultJWT 作为 <configId> 标识。 请在 jwtBuilder - JWT 构建器 (jwtBuilder) 中查找可用的 JWT 构建器配置属性。
- 在 Liberty 中以编程方式构建 JSON Web 令牌。
- 在 server.xml 文件中,添加 jwt-1.0 功能部件。
<featureManager>
<feature>jwt-1.0</feature>
...
</featureManager>
- 通过修改 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
- 通过在应用程序中实现 com.ibm.websphere.security.jwt.JwtBuilder 和 com.ibm.websphere.security.jwt.JwtToken API,以编程方式构建 JWT 令牌。
有关更多信息,请参阅 JSON Web 令牌 Java 文档。
- 创建 JwtBuilder 对象。
如果未指定配置标识,那么对象绑定到缺省
jwtBuilder 配置。
com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create();
如果指定配置标识,那么对象绑定到具有指定标识的
jwtBuilder 配置。
com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create("jwtBuilder_configuration_id");
- 修改令牌中的声明。
- 添加或更新声明: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");
- 修改配置的签名算法和签名密钥。
jwtBuilder.signWith("new_algorithm", new_key);
- 使用 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();