JSON Web Token Generator

This application is not supported by InterSystems Corporation. Use it at your own risk.

What's new in this version

  • Add purge blacklist method

JSON Web Token Generator

This is a simple class in order to generate, validate or blacklist a JSON Web Token.
Signature is encrypted with HS256 algorithm.

Generate a token


Set validityInSecond = 3600
Set jwt = ##class(dc.auth.jwt.JWTGenerator).generate("MySecretKey",validityInSecond)

Generated token



  "alg": "HS256",
  "typ": "JWT"


  "iat": 1587584761,
  "sub": "irisowner",
  "iss": "IRIS-IRISAPP",
  "exp": 1587588361,
  "nbf": 1587584761,
  "jti": "11215"

Customize payload

Add data and override default payload data :

Set validityInSecond = 3600
Set addPayloadData = { "name" : "Mike Wazowski", "sub":"override sub property" }
Set jwt = ##class(dc.auth.jwt.JWTGenerator).generate("MySecretKey",validityInSecond,addPayloadData)

Generated token


Payload data :

  "name": "Mike Wazowski",
  "sub": "override sub property",
  "iat": 1587585723,
  "iss": "IRIS-IRISAPP",
  "exp": 1587589323,
  "nbf": 1587585723,
  "jti": "11619"

Force payload value :

Force a payload without merging with default payload strucure:

Set validityInSecond = 3600
Set payload = { "name" : "Mike Wazowski", "sub":"irisuser", "iat":1587584761,"exp":1587588361, "aud":"" }
Set jwt = ##class(dc.auth.jwt.JWTGenerator).generate("MySecretKey",validityInSecond,payload,0,.jwtObj)

Generated token


Payload data :

  "name": "Mike Wazowski",
  "sub": "irisuser",
  "iat": 1587584761,
  "exp": 1587588361,
  "aud": ""

If you pass by reference a fifth argument to isValid method you may retrieve the dc.auth.jwt.JWTGenerator object instance.

Validate Token

Basic validation

Set isValid = ##class(dc.auth.jwt.JWTGenerator).isValid(jwt,"MySecretKey",.sc,,.jwtObj)

If the token is invalid, you can retrieve an error message with the status passed by reference

Write $SYSTEM.Status.GetOneErrorText(sc)

Ex: ERROR #5001: Signature Mismatch.

If you pass by reference a fifth argument to isValid method you may retrieve the dc.auth.jwt.JWTGenerator object instance. It's useful for payload data access ex :

zw jwt.payload

Payload property is a %DynamicObject.

Validation with additional matching payload data

Set payLoadMatch = {"name":"Mike Wazowski", "aud":""}
Set isValid = ##class(dc.auth.jwt.JWTGenerator).isValid(jwt,"MySecretKey",.sc,payLoadMatch,.jwtObj)
Write $SYSTEM.Status.GetOneErrorText(sc)

Result : ERROR #5001: aud mismatch.

We can also check if aud value match in specific list :

Set payLoadMatch = {"name":"Mike Wazowski", "aud": ["",""] }
Set isValid = ##class(dc.auth.jwt.JWTGenerator).isValid(jwt,"MySecretKey",.sc,payLoadMatch,.jwtObj)
Write $SYSTEM.Status.GetOneErrorText(sc)

Result : OK

Add a token to the black list

Blacklist method use jti property to store the blacklisted jwt.
If you use your own payload structure without jti property, blacklist method fail and return ERROR #5001: jti is null.

example :

Set validityInSecond = 3600
Set jwt = ##class(dc.auth.jwt.JWTGenerator).generate("MySecretKey",validityInSecond)  ; Generate a token for blacklist testing
Do ##class(dc.auth.jwt.JWTGenerator).blackList(jwt)

Now check the validity :

Set isValid = ##class(dc.auth.jwt.JWTGenerator).isValid(jwt,"MySecretKey",.sc)
Write !,$SYSTEM.Status.GetOneErrorText(sc)

Result : ERROR #5001: Token is black listed.

Purge blacklist

Remove all token from the blacklist:

Do ##class(dc.auth.jwt.JWTGenerator).purgeBlackList(0)

Remove only expired from the blacklist:

Do ##class(dc.auth.jwt.JWTGenerator).purgeBlackList()


Make sure you have git and Docker desktop installed.

ZPM Installation

install jwt-generator

Docker Installation

Clone/git pull the repo into any local directory

$ git clone https://github.com/intersystems-community/objectscript-docker-template.git

Open the terminal in this directory and run:

$ docker-compose build
  1. Run the IRIS container with your project:
$ docker-compose up -d

How to start coding

This repository is ready to code in VSCode with ObjectScript plugin. Install VSCode, Docker and ObjectScript plugin and open the folder in VSCode. Open /src/cls/PackageSample/ObjectScript.cls class and try to make changes - it will be compiled in running IRIS docker container. docker_compose

Feel free to delete PackageSample folder and place your ObjectScript classes in a form /src/Package/Classname.cls Read more about folder setup for InterSystems ObjectScript

The script in Installer.cls will import everything you place under /src into IRIS.

What's inside the repository


The simplest dockerfile which starts IRIS and imports Installer.cls and then runs the Installer.setup method, which creates IRISAPP Namespace and imports ObjectScript code from /src folder into it. Use the related docker-compose.yml to easily setup additional parametes like port number and where you map keys and host folders. Use .env/ file to adjust the dockerfile being used in docker-compose.


Dockerfile-zpm builds for you a container which contains ZPM package manager client so you are able to install packages from ZPM in this container. As an example of usage in installs webterminal


Dockerfile-web starts IRIS does the same what Dockerfile does and also sets up the web app programmatically


Settings file to let you immedietly code in VSCode with VSCode ObjectScript plugin)


Config file if you want to debug with VSCode ObjectScript

Read about all the files in this artilce

ZPM installation
zpm "install jwt-generator"
Developer Environment
Works with
InterSystems IRIS
Last updated