Package com.ebasetech.xi.api

Interface JWTBuilder

All Superinterfaces:
java.io.Serializable
public interface JWTBuilder
extends java.io.Serializable
JWTBuilder provides an interface to generate a JWT (JSON Web Token).

The JWTBuilder is accessed using EbaseSystem.getSecurityManager().

Since:
V5.6

  • Field Summary

    Fields
    Modifier and Type Field Description
    static java.lang.String A128CBC_HS256
    JWE algorithm name for A128CBC-HS256
    static java.lang.String A128GCM
    JWE algorithm name for A128GCM
    static java.lang.String A192CBC_HS384
    JWE algorithm name for A192CBC-HS384
    static java.lang.String A192GCM
    JWE algorithm name for A192GCM
    static java.lang.String A256CBC_HS512
    JWE algorithm name for A256CBC-HS512
    static java.lang.String A256GCM
    JWE algorithm name for A256GCM

  • Method Summary

    Modifier and Type Method Description
    JWTBuilder addClaim​(java.lang.String name, java.lang.Object value)
    Add a new claim to the JWT.
    JWTBuilder contentType​(java.lang.String cty)
    Set the content type header to the JWT Header.
    java.lang.String generateDirectJWE​(java.lang.String algorithm, javax.crypto.SecretKey secret)
    Generates Direct Encryption JSON Web Encryption (JWE) token to its compact format consisting of Base64URL-encoded parts delimited by period ('.') characters.
    java.lang.String generateJWSToken()
    Serializes the JSON Web Token (JWS) to its compact format consisting of Base64URL-encoded parts delimited by period ('.') characters.
    java.lang.String generateJWTToken()
    Serializes the JSON Web Token (JWT) to its compact format consisting of Base64URL-encoded parts delimited by period ('.') characters.
    JWTBuilder keyId​(java.lang.String kid)
    Set the key id header to the JWT Header.
    JWTBuilder setAudience​(java.lang.String audience)
    Sets RFC 7519 standard registered claim aud - Audience.
    JWTBuilder setExpiry​(java.util.Date expiry)
    Sets RFC 7519 standard registered claim exp - Expiration.
    JWTBuilder setExpiryMillies​(long expiry)
    Sets RFC 7519 standard registered claim exp - Expiration.
    JWTBuilder setHeaderParam​(java.lang.String name, java.lang.Object value)
    Add a new header to the JWT.
    JWTBuilder setId​(java.lang.String id)
    Sets RFC 7519 standard registered claim jti - JWT ID.
    JWTBuilder setIssuedAt​(java.util.Date date)
    Sets RFC 7519 standard registered claim iat - Issued At.
    JWTBuilder setIssuer​(java.lang.String issuer)
    Sets RFC 7519 standard registered claim iss - Issuer.
    JWTBuilder setNotBefore​(java.util.Date date)
    Sets RFC 7519 standard registered claim nbf - Not Before.
    JWTBuilder setPayload​(java.lang.String payload)
    Sets the JWT's payload to be a plaintext (non-JSON) string.
    JWTBuilder setSubject​(java.lang.String subject)
    Sets RFC 7519 standard registered claim sub - Subject.
    JWTBuilder signWithEC​(java.lang.String algorithm, java.security.PrivateKey privateKey)  
    JWTBuilder signWithHMAC​(java.lang.String algorithm, javax.crypto.SecretKey secret)  
    JWTBuilder signWithRSA​(java.lang.String algorithm, java.security.PrivateKey privateKey)  

  • Field Details

    • A128CBC_HS256

      static final java.lang.String A128CBC_HS256
      JWE algorithm name for A128CBC-HS256
      See Also:
      Constant Field Values

    • A192CBC_HS384

      static final java.lang.String A192CBC_HS384
      JWE algorithm name for A192CBC-HS384
      See Also:
      Constant Field Values

    • A256CBC_HS512

      static final java.lang.String A256CBC_HS512
      JWE algorithm name for A256CBC-HS512
      See Also:
      Constant Field Values

    • A128GCM

      static final java.lang.String A128GCM
      JWE algorithm name for A128GCM
      See Also:
      Constant Field Values

    • A192GCM

      static final java.lang.String A192GCM
      JWE algorithm name for A192GCM
      See Also:
      Constant Field Values

    • A256GCM

      static final java.lang.String A256GCM
      JWE algorithm name for A256GCM
      See Also:
      Constant Field Values

  • Method Details

    • setHeaderParam

      JWTBuilder setHeaderParam​(java.lang.String name, java.lang.Object value)
      Add a new header to the JWT.
      Parameters:
      name - name of the header
      value - of the header
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • keyId

      JWTBuilder keyId​(java.lang.String kid)
      Set the key id header to the JWT Header.
      Parameters:
      kid - of the key
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • contentType

      JWTBuilder contentType​(java.lang.String cty)
      Set the content type header to the JWT Header.
      Parameters:
      cty - content type of the header
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setId

      JWTBuilder setId​(java.lang.String id)
      Sets RFC 7519 standard registered claim jti - JWT ID.
      Parameters:
      id - of the JWT
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setIssuer

      JWTBuilder setIssuer​(java.lang.String issuer)
      Sets RFC 7519 standard registered claim iss - Issuer.
      Parameters:
      issuer - of the JWT
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setAudience

      JWTBuilder setAudience​(java.lang.String audience)
      Sets RFC 7519 standard registered claim aud - Audience.
      Parameters:
      audience - of the JWT
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setSubject

      JWTBuilder setSubject​(java.lang.String subject)
      Sets RFC 7519 standard registered claim sub - Subject.
      Parameters:
      subject - of the JWT
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setExpiryMillies

      JWTBuilder setExpiryMillies​(long expiry)
      Sets RFC 7519 standard registered claim exp - Expiration.
      Parameters:
      expiry - of the JWT in milliseconds
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setExpiry

      JWTBuilder setExpiry​(java.util.Date expiry)
      Sets RFC 7519 standard registered claim exp - Expiration.
      Parameters:
      expiry - on a specified date
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.6

    • addClaim

      JWTBuilder addClaim​(java.lang.String name, java.lang.Object value)
      Add a new claim to the JWT. The claim is added to the payload of the JWT. The payload is in JSON format. A claim name cannot be used more than once. If the name is repeated then the new value will be used.
      Parameters:
      name - name of the claim
      value - of the claim
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setPayload

      JWTBuilder setPayload​(java.lang.String payload)
      Sets the JWT's payload to be a plaintext (non-JSON) string. setPayload(String) cannot be used with 
      addClaim(String, Object)
      or of the set standard registered claims.
      Parameters:
      payload - The payload to set for the JWT
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setNotBefore

      JWTBuilder setNotBefore​(java.util.Date date)
      Sets RFC 7519 standard registered claim nbf - Not Before.
      Parameters:
      date - not before on a specified date
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • setIssuedAt

      JWTBuilder setIssuedAt​(java.util.Date date)
      Sets RFC 7519 standard registered claim iat - Issued At.
      Parameters:
      date - not issued at on a specified date
      Returns:
      JWTBuilder used to construct the JWT
      Since:
      V5.7

    • signWithHMAC

      JWTBuilder signWithHMAC​(java.lang.String algorithm, javax.crypto.SecretKey secret) throws java.security.InvalidKeyException
      Parameters:
      algorithm -
      secret - key to use to sign the JWS
      Returns:
      Throws:
      java.security.InvalidKeyException - if an error occurs generating the Key
      Since:
      V5.7
      See Also:
      KeyManager.SIGNATURE_HS256, KeyManager.SIGNATURE_HS384, KeyManager.SIGNATURE_HS512

    • signWithRSA

      JWTBuilder signWithRSA​(java.lang.String algorithm, java.security.PrivateKey privateKey) throws java.security.InvalidKeyException
      Parameters:
      algorithm -
      privateKey - key to use to sign the JWS
      Returns:
      Throws:
      java.security.InvalidKeyException - if an error occurs generating the Key
      Since:
      V5.7
      See Also:
      KeyManager.SIGNATURE_RS256, KeyManager.SIGNATURE_RS384, KeyManager.SIGNATURE_RS512

    • signWithEC

      JWTBuilder signWithEC​(java.lang.String algorithm, java.security.PrivateKey privateKey) throws java.security.InvalidKeyException
      Parameters:
      algorithm -
      privateKey - key to use to sign the JWS
      Returns:
      Throws:
      java.security.InvalidKeyException - if an error occurs generating the Key
      Since:
      V5.7
      See Also:
      KeyManager.SIGNATURE_ES256, KeyManager.SIGNATURE_ES384, KeyManager.SIGNATURE_ES512

    • generateJWTToken

      java.lang.String generateJWTToken() throws com.ebasetech.ufs.runtime.security.jwt.InvalidJWTokenException
      Serializes the JSON Web Token (JWT) to its compact format consisting of Base64URL-encoded parts delimited by period ('.') characters. This should be called after all the claims and optional signing key are set.
      Returns:
      compacted JWT

      Javascript example: 

       try {
  var SECRET_KEY = system.securityManager.keyManager.generateSecretKeyBytes(32);
  var key = system.securityManager.getKeyManager().generateHMACSecretKey(KeyManager.SIGNATURE_HS256, SECRET_KEY);

  var jwt = system.securityManager.jwtManager.jwtBuilder()
           .setId("myID")
           .setIssuedAt(new Date())
           .setSubject("subject")
           .setIssuer("issuer")
           .signWithHMAC(KeyManager.SIGNATURE_HS256, key)
           .generateJWTToken();
           
   //generates encoded JWT similar to:
   //eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJteUlEIiwiaWF0IjoxNTcyODc4NTY4LCJzdWIiOiJzdWJqZWN0IiwiaXNzIjoiaXNzdWVyIn0.UzlfOqi3SX9D8IkMi25bBJd07uE5AJCNS_kR7TUzs5U 
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
      Throws:
      com.ebasetech.ufs.runtime.security.jwt.InvalidJWTokenException
      Since:
      V5.7

    • generateJWSToken

      java.lang.String generateJWSToken() throws com.ebasetech.ufs.runtime.security.jwt.InvalidJWTokenException
      Serializes the JSON Web Token (JWS) to its compact format consisting of Base64URL-encoded parts delimited by period ('.') characters. This should be called in conjunction with setPayload.
      Returns:
      compacted JWE

      Javascript example: 

       try {
   var SECRET_KEY = system.securityManager.keyManager.generateSecretKeyBytes(32);
   var key = system.securityManager.getKeyManager().generateHMACSecretKey(KeyManager.SIGNATURE_HS256, SECRET_KEY);
   var jws = system.securityManager.jwtManager.jwtBuilder()
                          .setPayload("Hello World!!")
                          .signWithHMAC(KeyManager.SIGNATURE_HS256, key)
                          .generateJWSToken();
           
   //generates the JWS:
   //eyJhbGciOiJIUzI1NiJ9.SGVsbG8gV29ybGQhIQ.gJrSMuMs4JLaSrsfZWZ3HYpn_pok6BrcRc6JMl2SFq4 
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
      Throws:
      com.ebasetech.ufs.runtime.security.jwt.InvalidJWTokenException
      Since:
      V5.7
      See Also:
      setPayload(String)

    • generateDirectJWE

      java.lang.String generateDirectJWE​(java.lang.String algorithm, javax.crypto.SecretKey secret) throws com.ebasetech.ufs.runtime.security.jwt.InvalidJWTokenException
      Generates Direct Encryption JSON Web Encryption (JWE) token to its compact format consisting of Base64URL-encoded parts delimited by period ('.') characters.
      Content encryption classJWE enc identifierKey bitlength
      AES/CBC/HMAC/SHAA128CBC-HS256256
      A192CBC-HS384384
      A256CBC-HS512512
      AES/GCMA128GCM128
      A192GCM192
      A256GCM256
      Parameters:
      algorithm - to use for direct encryption. See below for supported types.
      secret - key used to generate the JWE. This should be generated using AES or HMAC hashing
      Returns:
      compacted JWE

      Javascript example: 

       try {
   var SECRET_KEY = system.securityManager.keyManager.generateSecretKeyBytes(32);
   var key = system.securityManager.getKeyManager().generateHMACSecretKey(KeyManager.SIGNATURE_HS256, SECRET_KEY);
   var jwe = system.securityManager.jwtManager.jwtBuilder()
                           .setId("myID")
                           .setIssuedAt(new Date())
                           .setSubject("subject")
                           .setIssuer("issuer")
                           .directEncryptionJWEToken(JWTBuilder.A256GCM, key);
           
   //generates the JWE:
   //eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..j-JO5GetBLP0VujO.NrLeeZZtyhjssDy7LBBOZcEoSUS47GrFbe0Hhtw-ejvpnTwGdzmkwuW2iTK0E8JKbO26m8vlZ3o5VGGiXVQ.P-CM_sSlqeMX7r7MEY_klg 
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
      Throws:
      com.ebasetech.ufs.runtime.security.jwt.InvalidJWTokenException
      Since:
      V5.7
      See Also:
      A128CBC_HS256, A128GCM, A192CBC_HS384, A192GCM, A256CBC_HS512, A256GCM, KeyManager.generateAESSecretKey(String), KeyManager.generateHMACSecretKey(String, String)