JWT Structure and Signature Validation

JWT (JSON Web Token) Structure and Signature Validation

1. Overview

A JSON Web Token (JWT) is a compact, URL-safe way to securely transmit information between two parties as a JSON object. It is digitally signed to ensure integrity and authenticity, making it a popular choice for stateless authentication in APIs, SPAs, and microservices.

2. JWT Structure

A JWT has three parts, separated by dots (.):

<Header>.<Payload>.<Signature>
  

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  

2.1 Header

• Specifies the token type (typ) and signing algorithm (alg).
• Example JSON:

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

• Base64Url encoded to form the first part of the JWT.

2.2 Payload

• Contains claims — statements about the user or entity.
• Types of claims:
  • Registered claims: iss, sub, aud, exp, iat.
  • Public claims: Custom claims agreed upon by both parties.
  • Private claims: Application-specific claims.
• Example JSON:

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

• Base64Url encoded to form the second part of the JWT.

2.3 Signature

• Ensures the token hasn’t been altered and was issued by a trusted source.
• Created by:
  1. Concatenating encodedHeader + "." + encodedPayload.
  2. Signing with the algorithm in the header using a secret (HMAC) or private key (RSA/ECDSA).
  3. Base64Url encoding the result.

3. JWT Creation Flow

[Client] -- Login Credentials --> [Auth Server]
[Auth Server] -- Validate Credentials --> [Database]
[Auth Server] -- Create Header & Payload --> [Sign with Secret/Private Key]
[Auth Server] -- Return JWT --> [Client Stores Token]
  

4. Signature Validation Process

1. Extract header, payload, and signature from the token.
2. Recreate the signature using:
   • The same algorithm (alg) from the header.
   • The server’s secret key (HMAC) or public key (RSA/ECDSA).
   • The string header.payload.
3. Compare the recreated signature with the token’s signature.
4. If they match, validate claims (exp, iss, aud).
5. If they don’t match, reject the token.

Signature Validation Flow Diagram

[Client] -- JWT --> [Server]
[Server] -- Split into Header, Payload, Signature
[Server] -- Recreate Signature using Key & Algorithm
[Server] -- Compare with Provided Signature
[Server] -- If Match --> Validate Claims --> Authorize
[Server] -- If No Match --> Reject
  

5. Example: HS256 Validation (Node.js)

const jwt = require('jsonwebtoken');

const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
const secret = "my_secret_key";

try {
  const decoded = jwt.verify(token, secret);
  console.log("Valid token:", decoded);
} catch (err) {
  console.error("Invalid token:", err.message);
}
  

6. Security Considerations

• Never trust the payload without verifying the signature.
• Use short expiration times (exp) to limit misuse.
• Store secrets/keys securely (environment variables, vaults).
• Avoid alg: none — it disables signature verification.
• Prefer asymmetric keys (RS256) for public APIs so the private key stays with the issuer.

7. Quick Visual Summary

HEADER:    { "alg": "HS256", "typ": "JWT" }
           Base64UrlEncode(header)

PAYLOAD:   { "sub": "1234567890", "name": "John Doe", "admin": true }
           Base64UrlEncode(payload)

SIGNATURE: HMACSHA256(
              base64UrlEncode(header) + "." + base64UrlEncode(payload),
              secret
           )