JWT: Create Node

The JWT: Create Node allows a workflow to create a JSON Web Token from a JSON payload, optional headers, and a secret and places the signed token on the payload.

Configuration

Configuration for the JWT: Create Node is broken up into several major sections.

Signing Configuration

Choose whether to pull the JWT signing configuration from your application’s Service Credentials (recommended) or to enter the values directly.

Choose a Service Credential

The issuer, algorithm, and secret are provided by the selected JWT Service Credential. This is the recommended option. This option is not available for Edge Workflows.

Enter Signing Configuration

• Issuer Template: (optional) The string template specifying the issuer of the token. This is most commonly your company’s domain (e.g. example.com), however it can be any string.
• Algorithm Type: The algorithm that is used to generate the JWT signature. The default value is “HS256”, and in most cases this does not need to be changed. If you provide an alg value as a custom header, the value of the header will override the value selected here. This allows for templating the algorithm if necessary.
• Secret Template: The secret that’s incorporated into the JWT signature. In most cases, this should be a string template referencing a value that can be retrieved later (for example, a value stored in a workflow global) so that the token can be verified later using a JWT: Verify Node. This value should be similar to a strong password and should never be shared.

Payload

Next, define a JSON object to serve as the payload for the JWT. The object can be defined one of two ways:

• JSON Template: When selected, you must define the properties and values of the token’s payload as a JSON template.
• Payload Path: When selected, you must enter a payload path to an object on your workflow’s payload to serve as the payload of the JWT.

Note: Losant automatically adds an iat (Issued At) value to the payload, which is a Unix timestamp (in seconds) at which the token was created. You may add your own iat value to override this.

Expiration

Choose whether this token should be considered invalid a specified amount of time after it is issued. The default value is 1 day after the token is issued, though you may change this to any relative amount of time in the future using the Expires In input and Time Unit dropdowns. This value will automatically be added to the token payload under the exp claim, with its value being the addition of the selected relative time (in seconds) to the iat value.

If an exp or iss value is specified in the token’s payload, those values will override the values specified here.

Note: In Edge Workflows, the ability to not set a token expiration date is only available in GEA version 1.2.1 or higher.

Headers

Optionally, you may also specify a JSON object to add custom headers to your JSON Web Token. This is useful for adding other universally accepted properties to the token, such as kid (Key Identifier).

As with the token’s payload, you may define the custom headers one of two ways:

• JSON Template: When selected, you may define the properties and values of the header as a JSON template.
• Payload Path: When selected, you may enter a payload path to an object on your workflow’s payload containing the header values you would like to append to the JWT.

Note: In Edge Workflows, the ability to set custom JWT headers is only available in GEA version 1.31.0 or higher.

Result Path

Finally, enter a payload path for where to place the signed JWT on your workflow payload. The result will be the JWT (as a string) or, if an error occurs, an error object with additional information about the exception.

Node Example

Given a workflow payload of:

{
  "globals": {
    "jwtSecret": "abcdefghijklmnopqrstuvwxyz"
  },
  "newUser": {
    "firstName": "Todd",
    "lastName": "Benzinger",
    "email": "todd@toddsdomain.com"
  }
}

And JWT: Create Node configuration of:

• Secret Template: {{globals.jwtSecret}}
• Algorithm: HS256
• JWT Payload Path: newUser
• Expiration: 1 day after issuance
• Issuer: losant.com

If the token is created at an Epoch timestamp of 1655139000, this results in the following being placed on the payload at your specified path:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaXJzdE5hbWUiOiJUb2RkIiwibGFzdE5hbWUiOiJCZW56aW5nZXIiLCJlbWFpbCI6InRvZGRAdG9kZHNkb21haW4uY29tIiwiaWF0IjoxNjU1MTM5MDAwLCJleHAiOjE2NTUyMjU0MDAsImlzcyI6Imxvc2FudC5jb20ifQ.oXAr1_D9obJhkTu2bahJe4eaCtHochMzpVa_AkSKwsM

Decoding this (which can also be done using the JWT: Decode Node) results in a header object of:

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

And a payload object of:

{
  "firstName": "Todd",
  "lastName": "Benzinger",
  "email": "todd@toddsdomain.com",
  "iat": 1655139000,
  "exp": 1655225400,
  "iss": "losant.com"
}

Node Errors

The most common error encountered with the JWT: Create Node is the token’s payload or custom headers failing to resolve to a valid JSON object.

For example, given a workflow payload of:

{
  "applicationName": "My Great Application"
}

And a JWT payload defined as a JSON template of:

{{applicationName}}

This leads to the following error placed on the workflow payload:

{
  "message": "dataTemplate template did not render to valid JSON",
  "type": "InvalidJson"
}

Related Nodes

• JWT: Decode Node
• JWT: Verify Node