JWT Creation and Integration in InterSystems IRISContestant

What is JWT?

JWT (JSON Web Token) is an open standard (RFC 7519) that offers a lightweight, compact, and self-contained method for securely transmitting information between two parties. It is commonly used in web applications for authentication, authorization, and information exchange.

A JWT is typically composed of three parts:

1. JOSE (JSON Object Signing and Encryption) Header
2. Payload
3. Signature

These parts are encoded in Base64Url format and concatenated with dots (.) separating them.

Structure of a JWT

Header

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

Payload

{"sub": "1234567890", "name": "John Doe", "iat": 1516239022}

Signature:
The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message has not been tampered with.

To create the signature:

1. base64 Encoded header and payload.
2. Apply the signing algorithm (e.g., HMAC SHA256 or RSA) with a secret key (for symmetric algorithms like HMAC) or a private key (for asymmetric algorithms like RSA).
3. Base64Url encode the result to obtain the signature.

Sample JWT. View the content of the JWT 

JWT Creation in IRIS

Note: Before 2024, the %OAuth2.JWT class was used for generating JWTs in IRIS. The %Net.JSON.JWT class is now the primary class for JWT creation, and I will use this class in the example code.

JWK overview

JWK represents a cryptographic key particularly for signing and verifying the JWTs. JWKs allow you to represent public keys (for verification) and private keys (for signing) in a standardized format that can be easily exchanged between systems. The JWKS holds multiple JWK's

JWT workflow

1. Construct your header as a %DynamicObject and add custom headers if needed.

2. Construct the body/claims directly as a %DynamicObject

3. Call the Create method from the %Net.JSON.JWT class.

Set sc = ##Class(%Net.JSON.JWT).Create(header, , claims, jwks, , .JWT)

Create JWK

Set sc = ##Class(%Net.JSON.JWK).Create("HS256","1212ASD!@#!#@$@#@$$#SDFDGD#%+_)(*@$SFFS",.privateJWK,.publicJWK)

This will return the private key

{"kty":"oct","k":"MTIxMkFTRCFAIyEjQCRAI0AkJCNTREZER0QjJStfKSgqQCRTRkZT","alg":"HS256"} 

Some important JWK Properties

"kty": "oct" - represents the symmetric algorithm
"kty": "RSA" / "kty": "EC" - represents the Asymmetric algorithm

Once the JWK is created, it can be added to the JWKS.

Let's create JWKS in IRIS

Set sc = ##class(%Net.JSON.JWKS).PutJWK(jwk,.JWKS)

This method returns the JWKS

Generating the JWT in IRIS

You can create Symmetric or Asymmetric key JWTs in IRIS. The %Net.JSON.JWK class is primarily used to generate the JWT. Before calling the method, ensure that you create and send the JWKS for both Symmetric and Asymmetric Encryption when generating the JWT.

Symmetric Encryption

Symmetric algorithms use a shared secret key, where both the sender and receiver use the same key to sign and verify the JWT. These algorithms, like HMAC (HS256, HS512, HS384), generate a hash (signature) for the JWT payload. This approach is not recommended for high-security systems since both signing and verification are exposed, posing potential security risks.

The Create method from the %Net.JSON.JWK class is used to generate the JWK. It takes two input parameters and returns two output parameters:

1. algorithm - The algorithm for which to create the JWK.
2. secert - The key which is used to sign and verify the JWT
3. privateJWK - The private JSON Web Key that is created.
4. publicJWK - The public JSON Web key that is created.

For symmetric key algorithms - you'll get privateJWK

for Asymmetric key algorithms- You'll get privateJWK and publicJWK

LEARNING>d ##class(Learning.JWT.NetJWT).SymmetricKeyJWT()
privateJWK={"kty":"oct","k":"MTIxMkFTRCFAIyEjQCRAI0AkJCNTREZER0QjJStfKSgqQCRTRkZT","alg":"HS256"}  ; <DYNAMIC OBJECT>
privateJWKS="{""keys"":[{""kty"":""oct"",""k"":""MTIxMkFTRCFAIyEjQCRAI0AkJCNTREZER0QjJStfKSgqQCRTRkZT"",""alg"":""HS256""}]}"
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsIngtYyI6InRlIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.PcCs_I8AVy5HsLu-s6kQYWaGvuwqwPAElIad11NpM_E

Asymmetric Encryption

Asymmetric encryption refers to the use of a key pair: one key for signing the token (private key) and another key for verifying the token (public key). This is different from symmetric encryption

Private Key: This key is used for signing the JWT. It is kept secret and should never be exposed.
Public Key: This key is used to verify the authenticity of the JWT. It can be safely shared and distributed because it cannot be used to sign new tokens.

You can generate the JWT Asymmetric encryption with private key/certificate via %SYS.X509Credentials. so, You have to store your certificate in this persistent class.

JWT in Web applications.

Starting from the 2023 version, IRIS includes built-in JWT creation for web applications by default. Ensure that JWT Authentication is enabled when setting up your web application

I've added the brief explanation about the configuration

1. Enable the JWT Authentication in your web application
2. If you haven't already, create a REST class
3. The default endpoint resource "/login" is included. Make a REST API call using basic authentication with the payload like {"user": "_SYSTEM", "password": "SYS"}.
4. The response will be a JSON containing the "access_token," "refresh_token," and other relevant details.
5. Use the "access_token" for authorization.