Package com.ibm.websphere.security.jwt
Class JwtBuilder
- java.lang.Object
- 
- com.ibm.websphere.security.jwt.JwtBuilder
 
- 
 public class JwtBuilder extends java.lang.ObjectThis 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 SummaryConstructors Constructor Description JwtBuilder()JwtBuilder(java.lang.String builderConfigId)
 - 
Method SummaryAll Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description JwtBuilderaudience(java.util.List<java.lang.String> newaudiences)Sets audience claim.JwtTokenbuildJwt()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.JwtBuilderclaim(java.lang.String name, java.lang.Object value)Sets the specified claim.JwtBuilderclaim(java.util.Map<java.lang.String,java.lang.Object> map)Sets the specified claims.JwtBuilderclaimFrom(JwtToken jwt)Retrieves all the claims from the given jwt.JwtBuilderclaimFrom(JwtToken jwt, java.lang.String claimName)Retrieves the specified claim from the given JwtToken.JwtBuilderclaimFrom(java.lang.String jsonOrJwt)Retrieves all the claims from the given json or jwt string.JwtBuilderclaimFrom(java.lang.String jsonOrJwt, java.lang.String claim)Retrieves the specified claim from the given json or jwt string.static JwtBuildercreate()Creates a newJwtBuilderobject using the default configuration ID .static JwtBuildercreate(java.lang.String builderConfigId)Creates a newJwtBuilderobject using the configuration ID provided.JwtBuilderexpirationTime(long exp)Sets expiration claim.JwtBuilderfetch(java.lang.String name)Retrieves the specified claim from the configured user registry.JwtBuilderissuer(java.lang.String issuerUrl)Sets issuer claim.JwtBuilderjwtId(boolean create)Sets JWT ID.JwtBuildernotBefore(long time_from)Sets "not before" claim.JwtBuilderremove(java.lang.String name)Removes the specified claim.JwtBuildersignWith(java.lang.String algorithm, java.lang.String key)Signing key and algorithm information.JwtBuildersignWith(java.lang.String algorithm, java.security.Key key)Signing key and algorithm information.JwtBuildersubject(java.lang.String username)Sets "subject" claim.
 
- 
- 
- 
Constructor Detail- 
JwtBuilderpublic JwtBuilder() 
 - 
JwtBuilderpublic JwtBuilder(java.lang.String builderConfigId) throws InvalidBuilderException- Throws:
- InvalidBuilderException
 
 
- 
 - 
Method Detail- 
createpublic static JwtBuilder create() throws InvalidBuilderException 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.
 
 - 
createpublic static JwtBuilder create(java.lang.String builderConfigId) throws InvalidBuilderException Creates a newJwtBuilderobject using the configuration ID provided.- Parameters:
- builderConfigId- ID of a corresponding- jwtBuilderelement in the server configuration.
- Returns:
- A new JwtBuilderobject tied to thejwtBuilderserver configuration element whoseidattribute matches the ID provided.
- Throws:
- InvalidConsumerException- Thrown if the builderConfigId is- null, or if there is no matching configuration ID in the server configuration.
- InvalidBuilderException
 
 - 
issuerpublic JwtBuilder issuer(java.lang.String issuerUrl) throws InvalidClaimException Sets issuer claim. This claim identifies the principal that issued the JWT.- Parameters:
- issuerUrl- This will be used to set the "iss" claim in the- JwtToken
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the issuerUrl is- null, or empty
 
 - 
audiencepublic JwtBuilder audience(java.util.List<java.lang.String> newaudiences) throws InvalidClaimException 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 the- JwtToken
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the newaudiences is- null, or empty
 
 - 
expirationTimepublic JwtBuilder expirationTime(long exp) throws InvalidClaimException 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 the- JwtToken
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the exp is before the current time
 
 - 
jwtIdpublic JwtBuilder jwtId(boolean create) 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 the- JwtToken
- Returns:
- JwtBuilderobject
 
 - 
notBeforepublic JwtBuilder notBefore(long time_from) throws InvalidClaimException 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 the- JwtToken
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the time_from is not a positive number
 
 - 
subjectpublic JwtBuilder subject(java.lang.String username) throws InvalidClaimException 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 the- JwtToken
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the username is- null, or empty
 
 - 
signWithpublic JwtBuilder signWith(java.lang.String algorithm, java.security.Key key) throws KeyException Signing key and algorithm information.- Parameters:
- algorithm- This String value represents the signing algorithm. This information will be used to sign the- JwtToken
- key- The private key- Keyto use for signing JWTs.
- Returns:
- JwtBuilderobject
- Throws:
- KeyException- Thrown if the key is- nullor if algorithm is- nullor empty
 
 - 
signWithpublic JwtBuilder signWith(java.lang.String algorithm, java.lang.String key) throws KeyException Signing key and algorithm information.- Parameters:
- algorithm- This String value represents the signing algorithm. This information will be used to sign the- JwtToken
- key- This represents shared secret that can be used to create the shared key
- Returns:
- JwtBuilderobject
- Throws:
- KeyException- Thrown if the key or algorithm is- nullor empty
 
 - 
claimpublic JwtBuilder claim(java.lang.String name, java.lang.Object value) throws InvalidClaimException Sets the specified claim.- Parameters:
- name- This is a String and represents the name of the claim
- value- This is an Object and represents the value of the claim
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the claim is- null, or the value is- nullor the value is not the correct type for the claim
 
 - 
claimpublic JwtBuilder claim(java.util.Map<java.lang.String,java.lang.Object> map) throws InvalidClaimException 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 is- null, or the value is- nullor the value is not the correct type for the claim
 
 - 
fetchpublic JwtBuilder fetch(java.lang.String name) throws InvalidClaimException 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 is- nullor empty
 
 - 
removepublic JwtBuilder remove(java.lang.String name) throws InvalidClaimException 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 is- nullor empty
 
 - 
claimFrompublic JwtBuilder claimFrom(java.lang.String jsonOrJwt, java.lang.String claim) throws InvalidClaimException, InvalidTokenException Retrieves the specified claim from the given json or jwt string.- Parameters:
- jsonOrJwt- This is a String and represents either base 64 encoded or decoded JWT payload in the json format or base 64 encoded JWT
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the claim is- nullor empty
- InvalidTokenException- Thrown if the jsonOrJwt is- nullor if the api fails to process the string
 
 - 
claimFrompublic JwtBuilder claimFrom(java.lang.String jsonOrJwt) throws InvalidClaimException, InvalidTokenException Retrieves all the claims from the given json or jwt string.- Parameters:
- jsonOrJwt- This is a String and represents either base 64 encoded or decoded JWT payload in the json format or base 64 encoded JWT
- Returns:
- JwtBuilderobject
- Throws:
- InvalidTokenException- Thrown if the jsonOrJwt is- nullor if the api fails to process the jsonOrJwt string
- InvalidClaimException
 
 - 
claimFrompublic JwtBuilder claimFrom(JwtToken jwt, java.lang.String claimName) throws InvalidClaimException, InvalidTokenException Retrieves the specified claim from the given JwtToken.- Parameters:
- jwt- This is a- JwtTokenobject
- claimName- This is a String and represents the name of the claim
- Returns:
- JwtBuilderobject
- Throws:
- InvalidClaimException- Thrown if the claim is- nullor empty
- InvalidTokenException- Thrown if the jwt is- nullor if the api fails to process the jwt
 
 - 
claimFrompublic JwtBuilder claimFrom(JwtToken jwt) throws InvalidTokenException Retrieves all the claims from the given jwt.- Parameters:
- jwt- This is a- JwtTokenobject and represents base 64 encoded JWT
- Returns:
- JwtBuilderobject
- Throws:
- InvalidTokenException- Thrown if the jwt is- nullor if the api fails to process the jwt
 
 - 
buildJwtpublic JwtToken buildJwt() throws JwtException, InvalidBuilderException 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 a- jwtBuilderelement with the ID used to instantiate this- JwtBuilderobject 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.
 
 
- 
 
-