Package com.ibm.websphere.security.jwt
Class JwtBuilder
java.lang.Object
com.ibm.websphere.security.jwt.JwtBuilder
This API is used for the creation of JSON Web Token (JWT) security tokens conforming the JWT specification as defined in:
JSON Web Token (JWT). The JWT tokens are self-described and can be validated
locally by the resource server or the client.
The code snippet that is shown here demonstrate how to use this API to generate the token. In the sample code, it is assumed
that the configuration id specified in the API matches the jwtBuilder element ID in the server configuration or the default id
that is provided in the Liberty runtime.
- Sample code for generating JWT Token
-
// 1. Create a JWTBuilder Object. JwtBuilder jwtBuilder = JwtBuilder.create("samplebuilder"); // Overwrite issuer. This is optional and if issuer is not specified either in the server configuration or here, // then the Builder will construct a default issuer Url jwtBuilder = jwtBuilder.issuer("http://host:port/issuer url"); // Overwrite any of the following // audience, expiration time, not before, subject, signing key or algorithm, jti jwtBuilder = jwtBuilder.audience(Arrays.asList(new String[]{"one", "two", "three"}); jwtBuilder = jwtBuilder.signWith("HS256", "shared secret"); // Overwrite or set any additional claims jwtBuilder = jwtBuilder.claim("custom claim", "custom value"); // 2. Create a JWT token JwtToken jwt = jwtBuilder.buildJwt();
- Since:
- 1.0
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionSets audience claim.buildJwt()Creates a newJwtTokenobject based on the information in thisJwtBuilderobject and based on the configuration for thejwtBuilderelement that is specified in the server configuration that matches the ID used to instantiate thisJwtBuilderobject.Sets the specified claim.Sets the specified claims.Retrieves all the claims from the given jwt.Retrieves the specified claim from the given JwtToken.Retrieves all the claims from the given json or jwt string.Retrieves the specified claim from the given json or jwt string.static JwtBuildercreate()Creates a newJwtBuilderobject using the default configuration ID .static JwtBuilderCreates a newJwtBuilderobject using the configuration ID provided.encryptWith(String keyManagementAlg, Key keyManagementKey, String contentEncryptionAlg) Sets token encryption information for creating JSON Web Encryption tokens.expirationTime(long exp) Sets expiration claim.Retrieves the specified claim from the configured user registry.Sets issuer claim.jwtId(boolean create) Sets JWT ID.notBefore(long time_from) Sets "not before" claim.Removes the specified claim.Signing key and algorithm information.Signing key and algorithm information.Sets "subject" claim.
-
Constructor Details
-
JwtBuilder
public JwtBuilder() -
JwtBuilder
- Throws:
InvalidBuilderException
-
-
Method Details
-
create
Creates a newJwtBuilderobject using the default configuration ID .- Returns:
- A new
JwtBuilderobject tied to thejwtBuilderserver configuration element with the default ID . - Throws:
InvalidBuilderException- Thrown if the JWT builder service is not available.
-
create
Creates a newJwtBuilderobject using the configuration ID provided.- Parameters:
builderConfigId- ID of a correspondingjwtBuilderelement in the server configuration.- Returns:
- A new
JwtBuilderobject tied to thejwtBuilderserver configuration element whoseidattribute matches the ID provided. - Throws:
InvalidConsumerException- Thrown if the builderConfigId isnull, or if there is no matching configuration ID in the server configuration.InvalidBuilderException
-
issuer
Sets issuer claim. This claim identifies the principal that issued the JWT.- Parameters:
issuerUrl- This will be used to set the "iss" claim in theJwtToken- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the issuerUrl isnull, or empty
-
audience
Sets audience claim. This claim in the JWT identifies the recipients that the token is intended for.- Parameters:
newaudiences- This is a list of Strings and will be used to set the "aud" claim in theJwtToken- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the newaudiences isnull, or empty
-
expirationTime
Sets expiration claim. This claim in the JWT identifies the expiration time of the token.- Parameters:
exp- This is a "long" value representing the time in milliseconds since January 1, 1970, 00:00:00 GMT. This will be used to set the "exp" claim in theJwtToken- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the exp is before the current time
-
jwtId
Sets JWT ID. This claim in the JWT provides a unique identifier of the token. This ID helps prevent the token from being replayed.- Parameters:
create- This is a boolean value that represents whether to generate a unique identifier. If the unique identifier is generated, then the "jti" claim is set in theJwtToken- Returns:
JwtBuilderobject
-
notBefore
Sets "not before" claim. This claim in the JWT identifies the time before which the JWT must not be accepted.- Parameters:
time_from- This is a "long" value representing the time in milliseconds since January 1, 1970, 00:00:00 GMT. This will be used to set the "nbf" claim in theJwtToken- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the time_from is not a positive number
-
subject
Sets "subject" claim. This claim in the JWT identifies the principal that is the subject of the token.- Parameters:
username- This String value represents the principal name. This will be used to set the "sub" claim in theJwtToken- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the username isnull, or empty
-
signWith
Signing key and algorithm information.- Parameters:
algorithm- This String value represents the signing algorithm. This information will be used to sign theJwtTokenkey- The private keyKeyto use for signing JWTs.- Returns:
JwtBuilderobject- Throws:
KeyException- Thrown if the key isnullor if algorithm isnullor empty
-
signWith
Signing key and algorithm information.- Parameters:
algorithm- This String value represents the signing algorithm. This information will be used to sign theJwtTokenkey- This represents shared secret that can be used to create the shared key- Returns:
JwtBuilderobject- Throws:
KeyException- Thrown if the key or algorithm isnullor empty
-
encryptWith
public JwtBuilder encryptWith(String keyManagementAlg, Key keyManagementKey, String contentEncryptionAlg) throws KeyException Sets token encryption information for creating JSON Web Encryption tokens.- Parameters:
keyManagementAlg- Specifies the encryption algorithm that is used to encrypt the Content Encryption Key.keyManagementKey- Key used to encrypt the Content Encryption Key, which is then used to encrypt the JWT plaintext to produce the JWE ciphertext.contentEncryptionAlg- Specifies the encryption algorithm that is used to encrypt the JWT plaintext to produce the JWE ciphertext.- Returns:
JwtBuilderobject- Throws:
KeyException- Thrown if an error is encountered using the provided key and encryption information
-
claim
Sets the specified claim.- Parameters:
name- This is a String and represents the name of the claimvalue- This is an Object and represents the value of the claim. Object can be a string, number, boolean, map, or list. Other object types will have their toString method called, which might not produce valid JSON- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the claim isnull, or the value isnullor the value is not the correct type for the claim
-
claim
Sets the specified claims.- Parameters:
map- This is a Map and represents the collection of claim name and claim value pairs to be set in the JWT.- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the claim isnull, or the value isnullor the value is not the correct type for the claim
-
fetch
Retrieves the specified claim from the configured user registry.- Parameters:
name- This is a String and represents the name of the claim- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the claim isnullor empty
-
remove
Removes the specified claim.- Parameters:
name- This is a String and represents the name of the claim to remove- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the claim isnullor empty
-
claimFrom
public JwtBuilder claimFrom(String jsonOrJwt, String claim) throws InvalidClaimException, InvalidTokenException Retrieves the specified claim from the given json or jwt string. JWT strings in JSON Web Encryption (JWE) format are not supported.- Parameters:
jsonOrJwt- This is a string that represents either a JWT payload in JSON format or a JWT in JWS format. The string may or may not be base64 encoded. Strings that are in JWE format are not supported.- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the claim isnullor emptyInvalidTokenException- Thrown if the jsonOrJwt isnullor if the api fails to process the string
-
claimFrom
Retrieves all the claims from the given json or jwt string. JWT strings in JSON Web Encryption (JWE) format are not supported.- Parameters:
jsonOrJwt- This is a string that represents either a JWT payload in JSON format or a JWT in JWS format. The string may or may not be base64 encoded. Strings that are in JWE format are not supported.- Returns:
JwtBuilderobject- Throws:
InvalidTokenException- Thrown if the jsonOrJwt isnullor if the api fails to process the jsonOrJwt stringInvalidClaimException
-
claimFrom
public JwtBuilder claimFrom(JwtToken jwt, String claimName) throws InvalidClaimException, InvalidTokenException Retrieves the specified claim from the given JwtToken.- Parameters:
jwt- This is aJwtTokenobjectclaimName- This is a String and represents the name of the claim- Returns:
JwtBuilderobject- Throws:
InvalidClaimException- Thrown if the claim isnullor emptyInvalidTokenException- Thrown if the jwt isnullor if the api fails to process the jwt
-
claimFrom
Retrieves all the claims from the given jwt.- Parameters:
jwt- This is aJwtTokenobject and represents base 64 encoded JWT- Returns:
JwtBuilderobject- Throws:
InvalidTokenException- Thrown if the jwt isnullor if the api fails to process the jwt
-
buildJwt
Creates a newJwtTokenobject based on the information in thisJwtBuilderobject and based on the configuration for thejwtBuilderelement that is specified in the server configuration that matches the ID used to instantiate thisJwtBuilderobject.- Returns:
JwtTokenobject.- Throws:
InvalidBuilderException- Thrown if ajwtBuilderelement with the ID used to instantiate thisJwtBuilderobject cannot be found in the server configuration.JwtException- Thrown if there is an error while creating the JWT, which includes creating the token payload, header, or signature.
-