jwt

(plugins.jwt)

Overview

The JWT plugin facilitates operations involving JSON Web Tokens, such as creating, signing, and verifying tokens. It provides various algorithms, including SHA256, SHA384, and SHA512 in combination with ECDSA or RSA, allowing flexible cryptographic operations. These algorithms can be configured with public and private keys for signing and verification, or with shared secrets for symmetric encryption.

Developers can use the builder() method to create tokens dynamically by specifying payloads and signing them with a chosen algorithm. Alternatively, simplified methods are available, like create(payload) or create(payload, expiresAt), which use pre-configured HmacSHA256 algorithms and shared secret keys for signing.

Token verification can be performed using verify(token) for default algorithms or verify(token, algorithm) for custom cryptographic configurations. The plugin also supports building algorithms based on external JSON Web Key Sets (JWKS) using the JWK(url) method. These features collectively enable robust and secure token-based authentication systems.

Returned Types

JWTClaims,

Methods Summarized

Type	Name	Summary
Algorithm	ES256(publicKey)	Builder to create a new Algorithm instance using SHA256withECDSA.
Algorithm	ES256(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA256withECDSA.
Algorithm	ES256(publicKey)	Builder to create a new Algorithm instance using SHA256withECDSA.
Algorithm	ES256(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA256withECDSA.
Algorithm	ES384(publicKey)	Builder to create a new Algorithm instance using SHA384withECDSA.
Algorithm	ES384(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA384withECDSA.
Algorithm	ES384(publicKey)	Builder to create a new Algorithm instance using SHA384withECDSA.
Algorithm	ES384(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA384withECDSA.
Algorithm	ES512(publicKey)	Builder to create a new Algorithm instance using SHA512withECDSA.
Algorithm	ES512(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA512withECDSA.
Algorithm	ES512(publicKey)	Builder to create a new Algorithm instance using SHA512withECDSA.
Algorithm	ES512(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA512withECDSA.
Algorithm	HS256()	Create a new Algorithm instance using HmacSHA256.
Algorithm	HS256(password)	Create a new HmacSHA256 Algorithm using the specified password.
Algorithm	HS384()	Create a new Algorithm instance using HmacSHA384.
Algorithm	HS384(password)	Create a new HmacSHA384 Algorithm using the specified password.
Algorithm	HS512()	Create a new Algorithm instance using HmacSHA512.
Algorithm	HS512(password)	Create a new Algorithm instance using HmacSHA512.
Algorithm	JWK(url)	Builder to create an algorithm instance based on a Json Web Key Set (JWKS) url.
Algorithm	RSA256(publicKey)	Builder to create a new Algorithm instance using SHA256withRSA.
Algorithm	RSA256(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA256withRSA.
Algorithm	RSA256(publicKey)	Builder to create a new Algorithm instance using SHA256withRSA.
Algorithm	RSA256(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA256withRSA.
Algorithm	RSA384(publicKey)	Builder to create a new Algorithm instance using SHA384withRSA.
Algorithm	RSA384(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA384withRSA.
Algorithm	RSA384(publicKey)	Builder to create a new Algorithm instance using SHA384withRSA.
Algorithm	RSA384(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA384withRSA.
Algorithm	RSA512(publicKey)	Builder to create a new Algorithm instance using SHA512withRSA.
Algorithm	RSA512(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA512withRSA.
Algorithm	RSA512(publicKey)	Builder to create a new Algorithm instance using SHA512withRSA.
Algorithm	RSA512(publicKey, privateKey)	Builder to create a new Algorithm instance using SHA512withRSA.
Builder	builder()	Returns a JSON Web Token token builder.
String	create(payload)	Create a JSON Web Token for the given payload that is signed with the (shared) secret key 'jwt.
String	create(payload, expiresAt)	Create a JSON Web Token for the given payload that is signed with the HS256 algorithm and the (shared) secret key 'jwt.
Object	verify(token)	Verify a JSON Web Token with the HS256 algorithm and the (shared) secret key 'jwt.
Object	verify(token, algorithm)	Verify a JSON Web Token with a specific algorithm.

Methods Detailed

ES256(publicKey)

Builder to create a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm builder used to sign or verify JSON Web Tokens.

ES256(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

• Array privateKey a byte array representing the privateKey (mostly used to create tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

ES256(publicKey)

Builder to create a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm builder used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.ES256('MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEV....')
     .kid('2X9R4H....')

ES256(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

• String privateKey a String representing the privateKey (mostly used to create tokens) The private key is assumed to be encoded according to the PKCS #8 standard.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.ES256.publicKey('MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEV....', 'MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wa...')
     .kid('2X9R4H....')

ES384(publicKey)

Builder to create a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm builder used to sign or verify JSON Web Tokens.

ES384(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

• Array privateKey a byte array representing the privateKey (mostly used to create tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

ES384(publicKey)

Builder to create a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm builder used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.ES384('MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEV....')
     .kid('2X9R4H....')

ES384(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

• String privateKey a String representing the privateKey (mostly used to create tokens) The private key is assumed to be encoded according to the PKCS #8 standard.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.ES384.publicKey('MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEV....', 'MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wa...')
     .kid('2X9R4H....')

ES512(publicKey)

Builder to create a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm builder used to sign or verify JSON Web Tokens.

ES512(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

• Array privateKey a byte array representing the privateKey (mostly used to create tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

ES512(publicKey)

Builder to create a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".

Parameters

• String publicKey a String representing the publicKey

Returns: Algorithm an algorithm builder used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.ES512('MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEV....')
     .kid('2X9R4H....')

ES512(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

• String privateKey a String representing the privateKey (mostly used to create tokens) The private key is assumed to be encoded according to the PKCS #8 standard.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.ES512.publicKey('MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEV....', 'MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wa...')
     .kid('2X9R4H....')

HS256()

Create a new Algorithm instance using HmacSHA256. Tokens specify this as "HS256". The password used to configure the algorithm is the (shared) secret key 'jwt.secret.password' that has to be configured on the admin page for this plugin.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.HS256()

HS256(password)

Create a new HmacSHA256 Algorithm using the specified password. Tokens specify this as "HS256".

Parameters

• String password the secret used to encrypt and decrypt the tokens

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

HS384()

Create a new Algorithm instance using HmacSHA384. Tokens specify this as "HS384". The password used to configure the algorithm is the (shared) secret key 'jwt.secret.password' that has to be configured on the admin page for this plugin.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.HS384()

HS384(password)

Create a new HmacSHA384 Algorithm using the specified password. Tokens specify this as "HS384".

Parameters

• String password the secret used to encrypt and decrypt the tokens

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.HS384('your secret password.....')

HS512()

Create a new Algorithm instance using HmacSHA512. Tokens specify this as "HS512". The password used to configure the algorithm is the (shared) secret key 'jwt.secret.password' that has to be configured on the admin page for this plugin.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.HS512.secret()

HS512(password)

Create a new Algorithm instance using HmacSHA512. Tokens specify this as "HS512".

Parameters

• String password the secret used to encrypt and decrypt the tokens

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.HS512.secret('your secret password.....')

JWK(url)

Builder to create an algorithm instance based on a Json Web Key Set (JWKS) url. Please note that the returned algorithm can only be used to verify tokens.

Parameters

• String url the jwks url

Returns: Algorithm an algorithm which can only be used to VERIFY Json Web Tokens.

Sample

var alg = plugins.jwt.JWK('https://....')
        var verified = plugins.jwt.verify(token, alg)

RSA256(publicKey)

Builder to create a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm used to sign or verify Json Web Tokens.

RSA256(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

• Array privateKey a byte array representing the privateKey (mostly used to create tokens)

Returns: Algorithm an algorithm used to sign or verify Json Web Tokens.

RSA256(publicKey)

Builder to create a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm used to sign or verify Json Web Tokens.

Sample

plugins.jwt.RSA256('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis...')
     .kid('2X9R4H....')

RSA256(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

• String privateKey a String representing the privateKey (mostly used to create tokens). The private key is assumed to be encoded according to the PKCS #8 standard.

Returns: Algorithm an algorithm used to sign or verify Json Web Tokens.

Sample

plugins.jwt.RSA256('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis...', 'MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvB...')
     .kid('2X9R4H....')

RSA384(publicKey)

Builder to create a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

RSA384(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

• Array privateKey a byte array representing the privateKey (mostly used to create tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

RSA384(publicKey)

Builder to create a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.RSA384('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis...')
     .kid('2X9R4H....')

RSA384(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

• String privateKey a String representing the privateKey (mostly used to create tokens) The private key is assumed to be encoded according to the PKCS #8 standard.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.RSA384.publicKey('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis...', 'MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvB...')
     .kid('2X9R4H....')

RSA512(publicKey)

Builder to create a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

RSA512(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".

Parameters

• Array publicKey a byte array representing the publicKey (mostly used to verify tokens)

• Array privateKey a byte array representing the privateKey (mostly used to create tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

RSA512(publicKey)

Builder to create a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.RSA512('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis...')
     .kid('2X9R4H....')

RSA512(publicKey, privateKey)

Builder to create a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".

Parameters

• String publicKey a String representing the publicKey (mostly used to verify tokens)

• String privateKey a String representing the privateKey (mostly used to create tokens) The private key is assumed to be encoded according to the PKCS #8 standard.

Returns: Algorithm an algorithm used to sign or verify JSON Web Tokens.

Sample

plugins.jwt.RSA512('MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis...','MIIEogIBAAKCAQEAnzyis1ZjfNB0bBgKFMSvvkTtwlvB...')
     .kid('2X9R4H....')

builder()

Returns a JSON Web Token token builder.

Returns: Builder an object which creates a jwt token.

Sample

var algorithm = plugins.jwt.ES256(publicKey, privateKey);

		   var token = plugins.jwt.builder()
                    .payload({'some': 'data', 'somemore': 'data2'})
                    .sign(algorithm);
		   if (token != null) {
		       //success
		       application.output(token);
		   }
        else {
            application.output('Could not create a token.');
        }

        var verified = plugins.jwt.verify(token, algorithm);
        if (verified != null) {
             //success
		       application.output(verified);
        }
        else {
            application.output('The token is not valid.');
        }

create(payload)

Create a JSON Web Token for the given payload that is signed with the (shared) secret key 'jwt.secret.password'. The 'jwt.secret.password' plugin property has to be configured on the admin page. The payload can be for example a user:username of the current user, so that with this token if it verifies with the same secret key you can assume it is the same user that wants to login. This is a shorthand method of the #builder() method with a HS256 algorithm.

Parameters

• Object payload a json containing the data, e.g. {'some': 'data', 'somemore': 'data2'}

Returns: String a string representing the encrypted data or null if the token cannot be generated

create(payload, expiresAt)

Create a JSON Web Token for the given payload that is signed with the HS256 algorithm and the (shared) secret key 'jwt.secret.password'. The 'jwt.secret.password' plugin property has to be configured on the admin page. The payload can be for example a user:username of the current user, so that with this token if it verifies with the same secret key you can assume it is the same user that wants to login. The expiresAt makes sure this token is only valid until that date. This is a shorthand method of the #builder() method with a HS256 algorithm.

Parameters

• Object payload a json containing the data, e.g. {'some': 'data', 'somemore': 'data2'}

• Date expiresAt the date when the created token expires, after the expired date the token won't be verified

Returns: String a string representing the encrypted data or null if the token cannot be generated

verify(token)

Verify a JSON Web Token with the HS256 algorithm and the (shared) secret key 'jwt.secret.password'. The 'jwt.secret.password' plugin property has to be configured on the admin page. This will only verify and return the payload that was given if the token was created with the HS256 algorithm and the 'jwt.secret.password'. Will also return null if the token passed its expire date.

Parameters

• String token a JSON Web Token

Returns: Object the payload or null if the token can't be verified

verify(token, algorithm)

Verify a JSON Web Token with a specific algorithm. The token could be external or created with the #builder() method.

This will only verify and return the payload that was given if the token could be verified with the provided algorithm. Will also return null if the token passed its expire date.

Parameters

• String token a JSON Web Token

• Algorithm algorithm an algorithm used to verify the signature

Returns: Object the payload or null if the token can't be verified

---