Class JwtBuilder


  • public class JwtBuilder
    extends java.lang.Object

    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 
      Constructor Description
      JwtBuilder()  
      JwtBuilder​(java.lang.String builderConfigId)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      JwtBuilder audience​(java.util.List<java.lang.String> newaudiences)
      Sets audience claim.
      JwtToken buildJwt()
      Creates a new JwtToken object based on the information in this JwtBuilder object and based on the configuration for the jwtBuilder element that is specified in the server configuration that matches the ID used to instantiate this JwtBuilder object.
      JwtBuilder claim​(java.lang.String name, java.lang.Object value)
      Sets the specified claim.
      JwtBuilder claim​(java.util.Map<java.lang.String,​java.lang.Object> map)
      Sets the specified claims.
      JwtBuilder claimFrom​(JwtToken jwt)
      Retrieves all the claims from the given jwt.
      JwtBuilder claimFrom​(JwtToken jwt, java.lang.String claimName)
      Retrieves the specified claim from the given JwtToken.
      JwtBuilder claimFrom​(java.lang.String jsonOrJwt)
      Retrieves all the claims from the given json or jwt string.
      JwtBuilder claimFrom​(java.lang.String jsonOrJwt, java.lang.String claim)
      Retrieves the specified claim from the given json or jwt string.
      static JwtBuilder create()
      Creates a new JwtBuilder object using the default configuration ID .
      static JwtBuilder create​(java.lang.String builderConfigId)
      Creates a new JwtBuilder object using the configuration ID provided.
      JwtBuilder encryptWith​(java.lang.String keyManagementAlg, java.security.Key keyManagementKey, java.lang.String contentEncryptionAlg)
      Sets token encryption information for creating JSON Web Encryption tokens.
      JwtBuilder expirationTime​(long exp)
      Sets expiration claim.
      JwtBuilder fetch​(java.lang.String name)
      Retrieves the specified claim from the configured user registry.
      JwtBuilder issuer​(java.lang.String issuerUrl)
      Sets issuer claim.
      JwtBuilder jwtId​(boolean create)
      Sets JWT ID.
      JwtBuilder notBefore​(long time_from)
      Sets "not before" claim.
      JwtBuilder remove​(java.lang.String name)
      Removes the specified claim.
      JwtBuilder signWith​(java.lang.String algorithm, java.lang.String key)
      Signing key and algorithm information.
      JwtBuilder signWith​(java.lang.String algorithm, java.security.Key key)
      Signing key and algorithm information.
      JwtBuilder subject​(java.lang.String username)
      Sets "subject" claim.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • create

        public static JwtBuilder create()
                                 throws InvalidBuilderException
        Creates a new JwtBuilder object using the default configuration ID .
        Returns:
        A new JwtBuilder object tied to the jwtBuilder server configuration element with the default ID .
        Throws:
        InvalidBuilderException - Thrown if the JWT builder service is not available.
      • create

        public static JwtBuilder create​(java.lang.String builderConfigId)
                                 throws InvalidBuilderException
        Creates a new JwtBuilder object using the configuration ID provided.
        Parameters:
        builderConfigId - ID of a corresponding jwtBuilder element in the server configuration.
        Returns:
        A new JwtBuilder object tied to the jwtBuilder server configuration element whose id attribute 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
      • issuer

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the issuerUrl is null, or empty
      • audience

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the newaudiences is null, or empty
      • expirationTime

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the exp is before the current time
      • jwtId

        public 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:
        JwtBuilder object
      • notBefore

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the time_from is not a positive number
      • subject

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the username is null, or empty
      • signWith

        public 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 Key to use for signing JWTs.
        Returns:
        JwtBuilder object
        Throws:
        KeyException - Thrown if the key is null or if algorithm is null or empty
      • signWith

        public 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:
        JwtBuilder object
        Throws:
        KeyException - Thrown if the key or algorithm is null or empty
      • encryptWith

        public JwtBuilder encryptWith​(java.lang.String keyManagementAlg,
                                      java.security.Key keyManagementKey,
                                      java.lang.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:
        JwtBuilder object
        Throws:
        KeyException - Thrown if an error is encountered using the provided key and encryption information
      • claim

        public 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. 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the claim is null, or the value is null or the value is not the correct type for the claim
      • claim

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the claim is null, or the value is null or the value is not the correct type for the claim
      • fetch

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the claim is null or empty
      • remove

        public 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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the claim is null or empty
      • claimFrom

        public JwtBuilder claimFrom​(java.lang.String jsonOrJwt,
                                    java.lang.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:
        JwtBuilder object
        Throws:
        InvalidClaimException - Thrown if the claim is null or empty
        InvalidTokenException - Thrown if the jsonOrJwt is null or if the api fails to process the string
      • claimFrom

        public JwtBuilder claimFrom​(java.lang.String jsonOrJwt)
                             throws InvalidClaimException,
                                    InvalidTokenException
        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:
        JwtBuilder object
        Throws:
        InvalidTokenException - Thrown if the jsonOrJwt is null or if the api fails to process the jsonOrJwt string
        InvalidClaimException
      • claimFrom

        public JwtBuilder claimFrom​(JwtToken jwt)
                             throws InvalidTokenException
        Retrieves all the claims from the given jwt.
        Parameters:
        jwt - This is a JwtToken object and represents base 64 encoded JWT
        Returns:
        JwtBuilder object
        Throws:
        InvalidTokenException - Thrown if the jwt is null or if the api fails to process the jwt
      • buildJwt

        public JwtToken buildJwt()
                          throws JwtException,
                                 InvalidBuilderException
        Creates a new JwtToken object based on the information in this JwtBuilder object and based on the configuration for the jwtBuilder element that is specified in the server configuration that matches the ID used to instantiate this JwtBuilder object.
        Returns:
        JwtToken object.
        Throws:
        InvalidBuilderException - Thrown if a jwtBuilder element with the ID used to instantiate this JwtBuilder object 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.