JSON Web Token (JWT) Authentication
Hi Everyone,
I would like to share the code and step-by-step instructions/or guideline for generating a JWT (JSON Web Token) signature, as well as how to test it using Postman / HealthConnect.
JWT is an open standard (RFC 7519) that defines a compact, URL-safe method for securely transmitting information between parties in the form of a JSON object.
Structure of a JWT:
A JWT consists of three parts, separated by dots (.):
- Header: The header contains about the token, specifying its type and the signing algorithm used. It typically includes the following fields:
- alg (Algorithm): Defines the signing algorithm (e.g., HMAC SHA256, RSA, etc.).
- typ (Type): Specifies the token type, which is always JWT.
- kid (Key ID): Identifies the key used for signature verification.
Example:
{
"alg": "HS256",
"typ": "JWT",
“kid”: “my-key”
}
- Payload: The payload contains the claims. It typically includes the following fields:
- iss -(Issuer) – Issuer of the token.
- Sub - (Subject) – Subject of the JWT (user identifier).
- Aud - (Audience) – Intended recipient of the token (JWT).
- Exp - (Expiration time) – Token expiry timestamp.
- jti – (Unique) - Token identifier.
- iat - (Issued At) – When the token was created.
- etc
Example:
{
"iss": "your issuer",
"sub": "your subject",
"aud": “your audience”,
“jti”: “your jti”,
“exp”: “your expiry time”
}
- Signature: it is created by encoding the header and payload, then signing them using a private or secret key. It ensures the integrity and authenticity of the token.
Signature= header + payload and a private or secret key
Example:
{
HMACSHA256( base64UrlEncode(header) +
"."
+ base64UrlEncode(payload),
secret key)
}
Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJVadQssw5c
PROCESS
Step 1: Generate Public and Private Keys
To generate a public-private key pair, you can use either OpenSSL or an online JSON Web Key (JWK) generator like mkjwk.
Using mkjwk (JSON Web Key Generator): mkjwk - JSON Web Key Generator
- Open the mkjwk tool.
- Set the following parameters:
- Key Size: Based on your requirements (e.g., 4096 bits).
- Key Use: Signature.
- Algorithm: Select the desired algorithm (e.g., RS512).
- Key ID (kid): Choose a name for the key identifier (this key value is required for code, see screenshot -1, below.).
- Show X.509 Certificate: Enable this option to generate an X.509 certificate if needed (e.g. “Yes”)
- This will generate both a public key and a private key for signing and verification.
Step 2: Generate and Sign a JWT Using Cache Object Script
The code implementation for this process is provided in Screenshot 1 below.
Screenshot 1: Cache Object Script Code
Step 3: Execute the Method – see screenshot 2 below.
Screenshot 2 – Method Execution.
Step 4: After executing the method in Step 3, copy the Base64-encoded output from the result displayed in Screenshot 2.
Step 5: Test in Postman - Follow these steps to send a request using Postman:
- Open Postman (if you don’t have it, just download and install it)
- Select the “POST” method and enter the appropriate “URL”.
- Navigate to the “Body” section, then add the required key-value pairs (needed to set up the key and value)
- In the "client_assertion" field, paste the Base64-encoded data from Step 4.
- Then “Send” to submit the request.
You should receive a response containing the access_token, expiration time, and other details based on - setup.
Screenshot 3: Postman Output
I hope this guide helps you. Once you have successfully generated and tested the JWT, you can proceed with configuring it in the HealthConnect Management Portal based on your requirements.
Thank you.
