Novulo JWT plugin

Wiki
1

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:

  1. Create an Algorithm Instance to sign with.
  2. 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.
Example Usage

Example: Creating a JWT with HS256

  1. Input Parameters:
    • Secret: “1234”.
    • Header:
{"typ":"JWT","alg":"HS256","kid":"ceea5cb08dabe3f8202839f07130b1ae1c294828"}
  • Payload:
{"iss":"miroslav","sub":"demo","aud":"community","iat":1738928028,"exp":1738928043}

  1. GetSigningAlgorithm Action Parameters:

    • algorithm_name: “hs”
    • hash_size: 256
    • sign_with: “1234”
    • is_webconfig_key: false

  2. CreateJWT Action Parameters:

    • headers: Header JSON string
    • payload: Payload JSON string
    • signer: Use the return value from the GetSigningAlgorithm action.

  3. Generated Token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNlZWE1Y2IwOGRhYmUzZjgyMDI4MzlmMDcxMzBiMWFlMWMyOTQ4MjgifQ.eyJpc3MiOiJtaXJvc2xhdiIsInN1YiI6ImRlbW8iLCJhdWQiOiJjb21tdW5pdHkiLCJpYXQiOjE3Mzg5MjgwMjgsImV4cCI6MTczODkyODA0M30.XnGHoozL0RUF4Bcen7KyhQzKccCHosBbnBo5XKzM_IE
  1. Validation:
    • Inspect the JWT using JWT.io.
    • Replace “your-256-bit-secret” with “1234” to validate the signature.
1 Like