How to Decode a JWT and Understand Its Contents

Introduction

JSON Web Tokens (JWTs) are a popular means of representing claims securely between two parties. They consist of three parts: the header, payload, and signature. In this guide, we’ll explore how to decode a JWT and understand what’s inside.

Structure of a JWT

A JWT is typically structured as follows:

header.payload.signature

• Header: Contains information about the type of token and the signing algorithm used (e.g., HMAC SHA256 or RSA).
• Payload: Contains the claims, which are statements about an entity (typically the user) and additional metadata.
• Signature: Used to verify that the sender of the JWT is who it claims to be and to ensure that the message wasn't changed along the way.

Decoding a JWT

1. Understanding the Segments

To decode a JWT, you need to separate it into its three components using the dot (.) as a delimiter. You can retrieve information from each component as follows:

• Header
• Payload
• Signature

2. Base64URL Decoding

JWTs use Base64URL encoding. This is similar to Base64 encoding but replaces + with -, / with _, and omits padding (=). To decode the header and payload, take the following steps:

function decodeBase64Url(base64Url) {
    const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
    const decodedData = Buffer.from(base64, 'base64').toString('utf8');
    return JSON.parse(decodedData);
}

3. Decoding Example

Let’s decode a sample JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0NTY3ODkwLCJleHBfdGltZSI6MTYyNTc0NDUwMH0.mF6fI70H7ctDXpH_effFCOzq84h8EpZ8OhMffwlB_Yc

1. Split the JWT:

   const jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0NTY3ODkwLCJleHBfdGltZSI6MTYyNTc0NDUwMH0.mF6fI70H7ctDXpH_effFCOzq84h8EpZ8OhMffwlB_Yc';
   const parts = jwt.split('.');
   const header = parts[0];
   const payload = parts[1];
   const signature = parts[2];
   

2. Decode and inspect:

   console.log(decodeBase64Url(header));  // Decoded Header
   console.log(decodeBase64Url(payload));  // Decoded Payload
   

Inspecting Claims in the Payload

Claims within the payload could include:

• Standard Claims: These include iss (issuer), exp (expiration time), and sub (subject).
• Custom Claims: These are specific to your application and can be anything relevant to your users or your API.

For example, the payload above when decoded might output:

{
  "user_id": 1234567890,
  "exp": 1625744500
}

Using In-browser Tools

While it's beneficial to understand how to decode JWTs manually, several free tools are available that streamline this process:

• MyAITools: Provides an in-browser tool for decoding JWTs. You simply paste your JWT, and it will display the decoded header and payload for you, along with detailed information about claims.
• JWT.io: Another popular option that allows for rapid decoding with visual feedback on the token structure.

These tools are particularly useful for quick checks during development.

Verifying the Signature

Although decoding the header and payload is straightforward, verifying the signature is crucial to ensure the integrity of the JWT. This typically involves:

1. Recreating the signature using the header and the payload as inputs with the same algorithm used to sign the JWT.
2. Comparing the recreated signature to the one in the JWT.

Here’s a quick example of verifying a JWT using Node.js:

const crypto = require('crypto');
function verifyJwt(jwt, secret) {
   const parts = jwt.split('.');
   const header = parts[0];
   const payload = parts[1];
   const signature = parts[2];

   const data = `${header}.${payload}`;
   const hmac = crypto.createHmac('SHA256', secret);
   hmac.update(data);
   const expectedSignature = hmac.digest('base64url');

   return expectedSignature === signature;
}

Conclusion

Decoding a JWT is a critical skill for developers working with APIs and authentication. Understanding its structure and how to decode each part allows for deeper insights into how claims are managed and validated. Remember to utilize in-browser tools like MyAITools for quick decoding and verification, but also practice manual decoding for a robust understanding.