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 and 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 and 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 Detail

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 Detail

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 class	JWE enc identifier	Key bitlength
AES/CBC/HMAC/SHA	A128CBC-HS256	256
	A192CBC-HS384	384
	A256CBC-HS512	512
AES/GCM	A128GCM	128
	A192GCM	192
	A256GCM	256

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)