Generating a JWT token in native NodeJS

4 min readJan 19, 2022

Plenty of people have written about what JWT tokens are and what they contain. I wanted to provide easy practical instructions on JWT token generation. This article is part of a series, including:

How to generate a JWT signing keys (this story)
Generating a JWT token in native NodeJS
Decoding and Validating a JWT token in native NodeJS

TL; DR;

NodeJS provides a crypto library natively in the ability to sign a JWT token using rsa private / public key pairs.

// Header
_base64( JSON.stringify(headerObj) ) + '.' +// Payload 
_base64( JSON.stringify(payloadObj) ) + '.' +// Signature 
_base64( crypto.sign(
         'RSA-SHA256',
         _base64( JSON.stringify(headerObj) ) + '.' +
         _base64( JSON.stringify(payloadObj) ),{
             key : PRIV_KEY,
             passphrase : PASSPHRASE
         })
       )

In the above example _base64 converts each element from ascii to base64url

Structure of a JWT

A JWT (JSON Web Token) is a small piece of data that has been encoded to a standard with a signature that allows the receiver of that data to validate who sent the data.

Example JWT Token:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.D_GlkbFwmfBAkaL2O07Tv9pK3nBYLwF2IsAdk7_Y29xg1shsuc-QRQub2dICWrSxGeRaTpg1WmOBRojNX6cVxL_LNJTjmPCMu9gdLLElSy47XUy_tqENLXf9dGqvBI5VO4sJIFyLMzf_ZLbJDOnu1Gey_kck5TZ8xYXSYnEgHJpvgltJ6HkJcNF2eoJ_GFgmP7hqa-xrvENbwo1VWFP3MTQbb10EyEmn5GwsONFveim37IOArTHNtzjhod6FIaEdRIPrGIQ9o_b2_Q-myb-gcBB5pO01aGCjyDDvlYx_QsivKrk5jiH1jxJsy5mud6-NspZ1qMKTZd0EZrYXf-fa2MGPJoV1QsqHrEZ6lyFKLyPiK5Y0rmN-dMiaoHzFvcS83-1eMv-TPJyelusojrWe-6a7UW7Fh-kN8GIMKQsl6CkkMEopQ_xxhYSHZa6KtJyiL5Aw29qAJYLAEwwH-Xhfo6uVH5RNCAuD2mWeR4B3yb1IJUj2FGffzl2BJQ_ilnh6Pksrs7R2vuF_HkIekb_3VMFLh-y9w5uH12s9VZei8eygsfGglgN4sJGog5zxCq_1yQ_ey8A3isdfxc--3t6YbOnEj-XbCXm9SOTzP4jWgvFMe4NvREvj4pR2L-SCMV4mzLJLA0QxLuOxdhWTk7my0h8eag0xpk2zAWQQBNu8Hdc

The data in the JWT is encoded into Base64url format and separated into 3 sections:

Header
Payload
Signature

Represented in the token as:

< header > . < payload > . < signature >

In the above token the Header is section of the JWT token upto the first . ie:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

We can easily do a conversion of this from Base64url using the following:

console.log( Buffer.from('eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9', 'base64').toString('ascii') );## Output
## {"alg":"RS256","typ":"JWT"}

The Payload section is contained between the first . and the second . , in the above example it is here:

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0## Base64 decoded as
## {"sub":"1234567890","name":"John Doe","admin":true,"iat":1516239022 }

Finally the Signature is generated by using (in our case) an RSA265 hash as specified in the header of the rsa private key that generated the token. The rsa public key can be used to verify this was generated by the private key, but itself cannot generate a signature.

This is the magic of JWT tokens using RSA public / private key pairs

Coding the JWT token

Prerequisites

Generate a rsa private and public key pair using my other article : How to generate a JWT signing keys
Install node : macOS brew install node windows install link
In a new folder, start a new project npm init -y

Because we are using standard node libraries no additional libraries or install is required.

The Code

Below is a code from the repo here.

I will breakdown the code line by line to provide a little commentary and hopefully explain what is going on.

const crypto = require('crypto'); NodeJS has included a version of crypto since v0.10 (i.e. from the start). We are using this crypto library to sign the JWT token using an rsa private key

optional const fs = require('fs'); Using NodeJS’s internal file system library allows us to load the private key from an external file. The key can be included in a const or environment variable as well.

optional const PASSPHRASE = process?.env?.passphrase || 'mykey'; rsa private keys allow a passphase to be set on them to make them more secure. This code loads the PASSPHRASE from an environment variable that can be setup during your CI/CD process or defaults to mykey

function _base64( element ) {
    return ( Buffer.isBuffer(element) ? element : Buffer.from( element ) ).toString('base64')
.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
}

The _base64 function converts ascii to base64url format. The base64url¹ format is a part of the JWT standard. This function will convert a string or buffer into a base64url format. We achieve this by leveraging NodeJS’s Buffer class.

const headerObj = {... The header for a JWT token is pretty standard, it must contain the typ: 'JWT' and in our case we are using an rsa key pair so the alg: 'RS256' .

const payloadObj = {... The payload contains the information you wish to share as part of the token.

const PRIV_KEY = fs=readFileSync(__dirname + '\\myRSA256.key', 'utf8'); We load the rsa private key from a file, the key can be encrypted using a passphrase or not, the code will work with either form. Generate your own rsa private and public key pair using this article.

Here is an example rsa private key, save as myRSA256.keythe passphrase for this key is mykey :

Finally we get to the build the JWT token and signing it, for ease of testing I just output the token to console log.

_base64(JSON.stringify(headerObj)) + '.' + // Headerand _base64(JSON.stringify(payloadObj)) + '.' + // PayloadInside a JWT the header and payload are both just JSON.stringify‘d and base64url encoded.

_base64( crypto.sign(
         'RSA-SHA256',
         _base64( JSON.stringify(headerObj) ) + '.' +
         _base64( JSON.stringify(payloadObj) ),{
             key : PRIV_KEY,
             passphrase : PASSPHRASE
         })
       ) // Signature

Inside the JWT the signature is once again base64url encoded, the contents of the encoding is an RSASHA256 hash of the header and payload.

crypto.sign is a NodeJS function what provides broad crypto functionality,
'RSA-SHA256' tells crypto to create a SHA256 hash using the rsa key,
_base64( JSON.stringify(headerObj) ) + '.' + _base64( JSON.stringify(payloadObj) ), provides the payload or data that is being hashed
{ key : PRIV_KEY, passphrase : PASSPHRASE } provides the key and passphrase to be used for the hash. If the rsa private key does not contain a passphrase this will still work.

I hope this helps someone, when I first started using JWT they did not make a lot of sense and I though I needed a library to encode and decode them, but the reality is much simpler. They are just base64 encoded, with a signature that can be verified, to help with that process I have a corresponding article about Decoding JWT token using native NodeJS.

[1] : https://datatracker.ietf.org/doc/html/rfc4648#section-5