Version: ACE 5

JWT

The purpose of the JWT Step is to help to retrieve data from JWT token, validate JWT token or sign data to be used as JWT token.

This video demonstrates, how JWT token can be retrieved, validated and signed.

Parameters

Common

Target path - name of the node in the doc, where contents of the JWT token will be stored.
Token - JWT token to verify or encode

Retrieving

note

Please note that decoding of JWT token values does not verify if the token has valid signature. You may want to validate token, before actually using values encoded...

caution

Do not store secrets and private keys as workspace variable, recommended practice is to set them through server environment variables.

Mode - decode

Validating

Mode - verify
Algorithm - validation method HS265 | RS256. Please refer to JWT spec to understand the differences. Consult party that have generated JWT token to understand, which algorithm has to be used to verify the token.
Public key (RS256) - public key to validate the token. The best practice is to store the key as variable and reference by variable name here.
Salt (HS256) - secret used to sign the token

note

Please note that when the token is not valid an error is thrown that then in next steps can be used to determine whether they should be executed. If you wish to stop execution of flow and return an error - we recommend using Catch step

Signing

Mode - sign
Algorithm - validation method HS265 | RS256. Please refer to JWT spec and JWT Playground to understand the differences. The algorithm used should be present in the JWT header, otherwise consult with the signing party regarding the algorithm used.
Private key (RS256) - private key to sign the token. The best practice is to store the key as environment variable and reference by variable name here.
Salt (HS256) - secret to use when signing the token
Data - token payload in JSON format
Expires in - time in seconds for which the token should be valid

Examples

Variables used for RS256 examples:

RSA_PRIVATE_KEY

RSA_PUBLIC_KEY

Encode (HS256)

Input doc:

{
  "secret": "token-password",
  "data": {
    "userId": 123,
    "role": "admin"
  }
}

Step configuration:

  - name: Step jwt
    config:
      mode: sign
      algorithm: HS256
      storeIn: .
      targetPath: token
      json: "{{data}}"
      expiresIn: 10y
      secret: "{{secret}}"
    stepType: jwt

Output doc:

{
  "secret": "token-password",
  "data": {
    "userId": 123,
    "role": "admin"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3MjIyLCJleHAiOjE5OTgwNzMyMjJ9.bzPFWxzaZ_KSr20FTT0rZUjpPktcNb4-upjktH8Mxw8"
}

Encode (RS256)

Input doc:

{
  "data": {
    "userId": 123,
    "role": "admin"
  }
}

Step configuration:

  - name: Step jwt
    config:
      mode: sign
      algorithm: RS256
      json: "{{data}}"
      storeIn: .
      targetPath: token
      expiresIn: 10y
      secret: "{{$env.RSA_PRIVATE_KEY}}"
    stepType: jwt

Output doc:

{
  "data": {
    "userId": 123,
    "role": "admin"
  },
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3NTU4LCJleHAiOjE5OTgwNzM1NTh9.aryIaNH39DtSvF6ZoajHdntsXkhj5jJJDUzd--QWRsheU2U2rnoDx0zVA_FXcZ2ueEpCqQP6kyVPSuwDTXJjp7OzGjfrJVlM4tj1d00ZCkuHqj_sOSj4UlX5AXX7lGLLru7TG6GvnOkl3OBGpD6e6a0Zz1dZPfv6KoX8HfI-2VPdMFKHmixtj4idG2uoR0oax4zZvRsvUyKTZ8rYQWB3mfb-HYRHqQ9Mz292pAwKgscRk_c8U-T2fmY_rHzf9cwftNxPCX6ieAtouLz8kdeazA_kw31ru6VPD3_HdsXkkI2fraNMTw2GyJnjl6SqIGuN6jbYIy5FMKVHZGnHM2wjIw"
}

Verify (HS256)

Input doc:

{
  "secret": "token-password",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3MjIyLCJleHAiOjE5OTgwNzMyMjJ9.bzPFWxzaZ_KSr20FTT0rZUjpPktcNb4-upjktH8Mxw8"
}

Step configuration:

  - name: Step jwt
    config:
      mode: verify
      algorithm: HS256
      targetPath: data
      token: "{{token}}"
      secret: "{{secret}}"
    stepType: jwt

Output doc:

{
  "secret": "token-password",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3MjIyLCJleHAiOjE5OTgwNzMyMjJ9.bzPFWxzaZ_KSr20FTT0rZUjpPktcNb4-upjktH8Mxw8",
  "data": {
    "userId": 123,
    "role": "admin",
    "iat": 1682497222,
    "exp": 1998073222
  }
}

Verify (RS256)

Input doc:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3NTU4LCJleHAiOjE5OTgwNzM1NTh9.aryIaNH39DtSvF6ZoajHdntsXkhj5jJJDUzd--QWRsheU2U2rnoDx0zVA_FXcZ2ueEpCqQP6kyVPSuwDTXJjp7OzGjfrJVlM4tj1d00ZCkuHqj_sOSj4UlX5AXX7lGLLru7TG6GvnOkl3OBGpD6e6a0Zz1dZPfv6KoX8HfI-2VPdMFKHmixtj4idG2uoR0oax4zZvRsvUyKTZ8rYQWB3mfb-HYRHqQ9Mz292pAwKgscRk_c8U-T2fmY_rHzf9cwftNxPCX6ieAtouLz8kdeazA_kw31ru6VPD3_HdsXkkI2fraNMTw2GyJnjl6SqIGuN6jbYIy5FMKVHZGnHM2wjIw"
}

Step configuration:

  - name: Step jwt
    config:
      mode: verify
      algorithm: RS256
      targetPath: data
      secret: "{{$env.RSA_PUBLIC_KEY}}"
      token: "{{token}}"
    stepType: jwt

Output doc:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3NTU4LCJleHAiOjE5OTgwNzM1NTh9.aryIaNH39DtSvF6ZoajHdntsXkhj5jJJDUzd--QWRsheU2U2rnoDx0zVA_FXcZ2ueEpCqQP6kyVPSuwDTXJjp7OzGjfrJVlM4tj1d00ZCkuHqj_sOSj4UlX5AXX7lGLLru7TG6GvnOkl3OBGpD6e6a0Zz1dZPfv6KoX8HfI-2VPdMFKHmixtj4idG2uoR0oax4zZvRsvUyKTZ8rYQWB3mfb-HYRHqQ9Mz292pAwKgscRk_c8U-T2fmY_rHzf9cwftNxPCX6ieAtouLz8kdeazA_kw31ru6VPD3_HdsXkkI2fraNMTw2GyJnjl6SqIGuN6jbYIy5FMKVHZGnHM2wjIw",
  "data": {
    "userId": 123,
    "role": "admin",
    "iat": 1682497558,
    "exp": 1998073558
  }
}

Decode

Input doc:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3MjIyLCJleHAiOjE5OTgwNzMyMjJ9.bzPFWxzaZ_KSr20FTT0rZUjpPktcNb4-upjktH8Mxw8"
}

Step configuration:

  - name: Step jwt
    config:
      mode: decode
      targetPath: data
      token: "{{token}}"
    stepType: jwt

Output doc:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiaWF0IjoxNjgyNDk3MjIyLCJleHAiOjE5OTgwNzMyMjJ9.bzPFWxzaZ_KSr20FTT0rZUjpPktcNb4-upjktH8Mxw8",
  "data": {
    "userId": 123,
    "role": "admin",
    "iat": 1682497222,
    "exp": 1998073222
  }
}

Parameters​

Common​

Retrieving​

Validating​

Signing​

Examples​

Encode (HS256)​

Encode (RS256)​

Verify (HS256)​

Verify (RS256)​

Decode​

Parameters

Common

Retrieving

Validating

Signing

Examples

Encode (HS256)

Encode (RS256)

Verify (HS256)

Verify (RS256)

Decode