Novulo JWT plugin

m.gechev · March 13, 2025, 3:11pm

Novulo JWT Plugin

The Novulo JWT Plugin provides actions for creating signed JWT tokens.

Supported Signing Methods

The plugin can digitally sign data using one of the following methods:

Secret (HMAC Algorithm): Supports hash sizes of 256, 384, and 512 (JWT terms: HS256, HS384, HS512).
Public/Private Key Pair (RSA Algorithm): Supports hash sizes of 256, 384, and 512 (JWT terms: RS256, RS384, RS512).

Usage

Building JWTs with this plugin is a two-step process:

Create an Algorithm Instance to sign with.
Create and Sign the JWT using the algorithm instance.

This approach supports easy extension for more signing algorithms and allows for digitally signing data in any format.

Actions

1. GetSigningAlgorithm Action

Creates an object instance for use in signing actions like CreateJWT or SignData.

Parameters

Name	Type	Required	Default	Description
`algorithm_name`	String	Yes	-	Set to `rs` for RSA signing or `hs` for HMACSHA signing.
`hash_size`	Int	No	256	Hash size: `256`, `384`, or `512`.
`sign_with`	Mixed	Yes	-	Either a String (for HS mode) or a File (.pfx or certificate file for RS mode).
`password`	String	No	-	Used for password-protected RSA certificates.
`secret_encoding`	String	No	UTF-8	Encoding for HS mode (only for `SignData` action).
`is_webconfig_key`	Bool	No	False	If `true`, the value is read from Webconfig.

Usage of is_webconfig_key:

When is_webconfig_key is set to true:
- RSA Mode: The password parameter should reference the webconfig key containing the certificate’s password.
- HMACSHA Mode: The sign_with parameter should reference the webconfig key containing the secret string.
When is_webconfig_key is set to false, the actual value should be directly provided in the sign_with or password parameters.
Example webconfig:

<add key="NovuloJwt.mysecret.secret" value="1234"/>
<add key="NovuloJwt.mycert.password" value="1234"/>

Format:
- NovuloJwt.{unique_name}.secret - for HS secrets.
- NovuloJwt.{unique_name}.password - for RSA certificate passwords.

Return Values

success/error: Standard action return values.
signing_algorithm: The signer instance for subsequent signing actions.

2. CreateJWT Action

Creates a signed JWT token using the provided signer.

Parameters

Name	Type	Required	Description
`headers`	Mixed	Yes	JWT header as a `String` or `List<Tuple<String,Mixed>>`.
`payload`	Mixed	Yes	JWT payload (claims) as a `String` or `List<Tuple<String,Mixed>>`.
`signer`	Mixed	Yes	The `signing_algorithm` returned by `GetSigningAlgorithm`.

Return Values

success/error: Standard action return values.
token: The signed JWT token as a String.

About `headers` and `payload` Parameters

Using List<Tuple<String,Mixed>> is recommended, as values are serialized to JSON and escaped according to JWT specs. The mandatory typ and alg keys are set automatically.
Using String requires pre-serialized and properly formatted JSON:
- Ensure typ and alg are correctly set.
- Avoid invalid characters (like \r\n).
- Ensure proper escaping according to JWT specs.

3. SignData Action

Digitally signs input data using the provided signer instance (supports both RSA and HMACSHA).

Parameters

Name	Type	Required	Description
`signer`	Mixed	Yes	The `signing_algorithm` from `GetSigningAlgorithm`.
`data`	Mixed	Yes	The data to sign (can be a file).
`input_encoding`	String	No	Encoding for input data (`hex`, `base64`, `utf-8`, `ascii`, `unicode`).
`output_encoding`	String	No	Format for the output signature (`hex` or `base64`).

Return Values

success/error: Standard action return values.
signed_data: The generated signature in the specified format.

4. DecodeJwt action

Takes input string which is expected to be a JWT (Json web token) and decodes it into something readable. Extracts the signature as well, so the signature can be verified

Parameters

Name	Type	Required	Description
token	String	Yes	The JWT to decode

Return Values

success/error: Standard action return values.
header - List<Tuple<String,Mixed>> populated with the Claims in the Header of the JWT
header_as_string - the base64urlencoded representation of the header of the JWT. This is mainly used for validation purposes later on. Use the Header return value instead if manual processing is needed.
payload - List<Tuple<String,Mixed>> populated with the Claims in the Payload of the JWT
payload_as_string - the base64urlencoded representation of the paylod of the JWT. This is mainly used for validation purposes later on. Use the Payload return value instead if manual processing is needed.
signature - Mixed (actually a byte) representation of the signature of the JWT. Used for validation purposes, together with the VerifySignature action

5. GetCertInfo Action

Takes a ISigning algorithm instance ( from GetSigningAlgorithm or GetRSSigningAlgorithm) and extracts information from the certificate that can be publicly exposed.
Meant to be used for OAuth2 and OIDC related configuration. Usage outside of that is probably quite limited.

Parameters

Name	Type	Required	Description
signing_algorithm	Mixed	yes	RS Signing algorithm instance returned from GetSigningAlgorithm or GetRSSigningAlgorithm actions

Return Values

success/error: Standard action return values.
public_key: String that represents the Public key of the RS Signing algorithm
thumbprint : the thumbprint of the public key of the certificate
modulus : the modulus of the public key of the certificate
exponent : the exponent of the public key of the certificate

6. GetHSSigningAlgorithm Action

Similar to the GetSigningAlgorithm action. The GetSigningAlgorithm action can instantiate (based on how it is configured) a HS or RS signer. The GetHSSigningAlgorithm action instantiates only a HS one and its parameters are limited to the one only needed by a HS signer

Parameters

Name	Type	Required	Description
hash_size	Int	No (default 256)	The hash size to use
secret	String	Yes	The secret to sign with. Can be the secret as a string itself or reference to a key in the webconf (for example if it is webconfing value reference and value is “testsecret”, the Value in the webconfig should be specified as NovuloJwt.testsecret.secret)
secret_encoding	string	No	The encoding type of the secret. Default is utf-8
is_webconfig_key	Boolean	No	default false; if set to true, the value provided for the secret parameter becomes the reference key in the webconfig used to retrieve the actual value

Return Values

success/error: Standard action return values.
signing_algorithm: HS signing algorithm instance configured with the provided parameters. Should be used with other action to sign data / verify signatures

7. GetRSSigningAlgorithm action

Similar to the GetSigningAlgorithm action. The GetSigningAlgorithm action can instantiate (based on how it is configured) a HS or RS signer. The GetRSSigningAlgorithm action instantiates only a RS one and its parameters are limited to the one only needed by a RS signer

Parameters

Name	Type	Required	Description
hash_size	Int	No (default 256)	The hash size to use
key_file	File	Yes	The private key to sign data with
Password	string	No (yes, if the Private key is password protected	The password used to unlock the private key (if password protected). Can be also a reference to a webconfig value ( key in webconfig is in the format NovuloJwt.<password_value>.password ; the value of the webconfig key is the actual password)
is_webconfig_key	boolean	no (default false)	indicates if the password parameter is a reference to a webconfig key or not

Return Values

success/error: Standard action return values.
signing_algorithm: RS signing algorithm instance configured with the provided parameters. Should be used with other action to sign data / verify signatures

8. VerifySignature Action

Used to verify the signature and validity of a JWT.

Parameters

Name	Type	Required	Description
signing_algorithm	Mixed	Yes	A SignerAlgorithm instance ( see GetSigningAlgorith, GetHSSigningAlgorithm or GetRSSigningAlgoritm actions)
header_part	String	Yes	Base64Url encoded header part of a JWT ( see DecodeJWT action)
payload_part	String	Yes	Base64url encoded payload part of a JWT ( see DecodeJWT action)
signature	Mixed	Yes	The signature bytes of a JWT ( see DecodeJWT action)

Return Values

success/error: Standard action return values.
is_valid: Indicates if the JWT and Signature are successfully validated (and not tampered with) against the provided signing_algorithm (which is configured with the private credentials we have)

9. CalculateAtHashClaim action

Calculates the at_hash for an access token. Used for IdTokens in OIDC context. No/Limited usage outside of that.

Parameters

Name	Type	Required	Description
access_token	String	Yes	The access token to hash for at_hash claim value in a ID token
hash_size	Int	Yes	The hash size needed to determine what hash algorithm to instantiate

Return Values

success/error: Standard action return values.
at_hash: The generated hash to include under at_hash claim in a JWT Id token ( see As hash claim specs )

Example Usage

Example: Creating a JWT with HS256

Input Parameters:
- Secret: “1234”.
- Header:

{"typ":"JWT","alg":"HS256","kid":"ceea5cb08dabe3f8202839f07130b1ae1c294828"}

Payload:

{"iss":"miroslav","sub":"demo","aud":"community","iat":1738928028,"exp":1738928043}

GetSigningAlgorithm Action Parameters:
- algorithm_name: “hs”
- hash_size: 256
- sign_with: “1234”
- is_webconfig_key: false
CreateJWT Action Parameters:
- headers: Header JSON string
- payload: Payload JSON string
- signer: Use the return value from the GetSigningAlgorithm action.
Generated Token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNlZWE1Y2IwOGRhYmUzZjgyMDI4MzlmMDcxMzBiMWFlMWMyOTQ4MjgifQ.eyJpc3MiOiJtaXJvc2xhdiIsInN1YiI6ImRlbW8iLCJhdWQiOiJjb21tdW5pdHkiLCJpYXQiOjE3Mzg5MjgwMjgsImV4cCI6MTczODkyODA0M30.XnGHoozL0RUF4Bcen7KyhQzKccCHosBbnBo5XKzM_IE

Validation:
- Inspect the JWT using JWT.io.
- Replace “your-256-bit-secret” with “1234” to validate the signature.

Mihai · September 10, 2025, 9:24am

Update – New Return Values

The GetCertInfo action has been extended with two optional return values. These are added to support scenarios where a client assertion JWT must include certificate thumbprint information.

New Return Values

x5t: Base64url-encoded SHA-1 hash of the DER-encoded certificate.
x5t_s256: Base64url-encoded SHA-256 hash of the DER-encoded certificate.

Purpose

These values can be placed in the JWT header (x5t or x5t#S256) when building a client assertion. Both values are standard ways to reference a certificate without transmitting the full certificate information.

x5t is based on SHA-1 and exists for backward compatibility with older systems.
x5t_s256 is stronger and a newer and is based on SHA-256.

Topic		Replies	Views
Novulo OAuth2.0 configuration and usage Wiki rest , plugin	6	396	October 16, 2025
Serialization plugin (P173) Wiki	3	140	July 15, 2024
Using bearer token for authentication for end points [Q&A] Components, Datasets and Plug-ins rest	6	180	November 27, 2024
Explanation of the data.xml Wiki plugin	0	144	July 11, 2024
Require website user authentication [Q&A] Components, Datasets and Plug-ins rest	4	69	September 23, 2024

Novulo JWT plugin

Novulo JWT Plugin

Supported Signing Methods

1. GetSigningAlgorithm Action

Parameters

Return Values

2. CreateJWT Action

Parameters

Return Values

About headers and payload Parameters

3. SignData Action

Parameters

Return Values

4. DecodeJwt action

Parameters

Return Values

5. GetCertInfo Action

Parameters

Return Values

6. GetHSSigningAlgorithm Action

Parameters

Return Values

7. GetRSSigningAlgorithm action

Parameters

Return Values

8. VerifySignature Action

Parameters

Return Values

9. CalculateAtHashClaim action

Parameters

Return Values

Example: Creating a JWT with HS256

Update – New Return Values

New Return Values

Purpose

Related topics

About `headers` and `payload` Parameters