You can programmatically build JSON Web Token (JWT) tokens by configuring the JWT builder
element in the server configuration and implementing the
com.ibm.websphere.security.jwt.JwtBuilder and
com.ibm.websphere.security.jwt.JwtToken APIs in your applications.
About this task
For information about JWT APIs, see the JSON Web Token Java documentation or the API documentation
included in the product in the ${wlp.install.dir}/dev directory.
Procedure
- In the server.xml file, add the jwt-1.0 feature.
<featureManager>
<feature>jwt-1.0</feature>
...
</featureManager>
- Configure the JWT builder by modifying the jwtBuilder element.
For information about jwtBuilder attributes that you can configure, see JWT Builder (jwtBuilder).
When you add the
jwt-1.0 feature and save your changes,
Liberty adds the following default
jwtBuilder
element.
<jwtBuilder id="defaultJWT">
</jwtBuilder>
In this default configuration, the following values are assumed:
- The exp claim is 2 hours after the token creation time. You can configure this
value on the expiry attribute.
- The iss claim is set to
https://<host_name>:<ssl_port>/jwt/defaultJWT.
Configure the issuer on the issuer attribute.
- The JWT is signed by using the RS256 algorithm with a private key in the default keystore of the
server. This configuration assumes that a default keystore is configured for the server, that the
default keystore contains a single private key, and that the private key can be used for signing. If
you specify a different keystore on the keyStoreRef attribute, the private key from
the specified keystore is used. If the keyAlias attribute is not configured and the
keystore contains only one private key, that private key is used in the signature.
You can reconfigure this default jwtBuilder element, or create one or more other
jwtBuilder elements. Each jwtBuilder element must have a unique,
URL-safe string specified as the id attribute. If the ID is missing, the
jwtBuilder is not processed.
If the JWT token is signed by using the RS256 algorithm, you can configure the JWT builder to
sign the JWT token with JSON Web Key (JWK) by setting
jwkEnabled="true". When JWK
is enabled, the JWT builder dynamically generates key pairs and sign the JWT token with the private
key. To validate the signature, the JWT consumer can retrieve the key from the JWK API, which has
the following format:
https://<host_name>:<ssl_port>/jwt/ibm/api/<jwtBuilder_configuration_id>/jwk
- Programmatically build JWT tokens by implementing the
com.ibm.websphere.security.jwt.JwtBuilder and
com.ibm.websphere.security.jwt.JwtToken APIs in your application.
For more information, see the JSON Web Token Java documentation.
- Create a JwtBuilder object.
If you do not specify a configuration ID, the object is tied to the default
jwtBuilder
configuration.
com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create();
If you specify a configuration ID, the object is tied to the
jwtBuilder
configuration with the specified
ID.
com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create("jwtBuilder_configuration_id");
- Modify the claims in the token.
- Add or update a claim: jwtBuilder.claim("claim_name",
"claim_value");
jwtBuilder.claim("role", "monitor");
- Delete a claim:
jwtBuilder.remove("claim_name");
jwtBuilder.remove("role");
- Fetch a claim from the Liberty Federated
User Registry: jwtBuilder.fetch("attribute_name");
This fetch
call tells the JwtBuilder object to search the Federated User Registry for the user
name identified by the sub claim of the JWT. The JwtBuilder object
fetches the value of the specified attribute and creates a new claim based on that attribute. The
name of the new claim is set to the attribute name, and the value of the new claim is set to the
attribute value.
- Copy a claim from an existing JWT or JSON object:
jwtBuilder.claimFrom(JSON_or_JWT,
"claim_name");
- Modify the configured signature algorithm and signing key.
jwtBuilder.signWith("new_algorithm", new_key);
- Build the token by using the com.ibm.websphere.security.jwt.JwtToken
API.
JwtToken jwtToken = jwtBuilder.buildJwt();
String jwtTokenString = jwtToken.compact();
JSON Web Token API examples
The following example creates a new
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();
The resulting JWT is signed with the server's default private key and contains the following
claims.
{
"aud": "https://acme.com/rs",
"iss": "https://sso.com/ibm/op",
"iat": 1388440863, "exp": 1388444763,
"uid": "hasys123haksiqws",
"sub": "tom@op.com",
"scope": "impersonator monitor"
}
The following example builds the
newToken JWT from another JWT,
goToken.
JwtToken newToken = JwtBuilder.create().claim(Claims.AUDIENCE, "https://acme.com/rs").claimFrom(goToken, "sub").claim(goToken, "uid").claim(goToken, "scope").buildJwt();