JWT Authentication

Introduction: The Hotel Key Card Analogy

Imagine checking into a hotel.

At the reception desk:

1. You verify your identity.
2. The receptionist gives you a key card.
3. That key card allows you to:
   • Enter your room
   • Access elevators
   • Use certain hotel services

Important observations:

• The hotel staff doesn't verify your identity every time.
• The key card itself proves your authorization.
• The hotel trusts the encoded information inside the card.

This is exactly how JWT authentication works.

Instead of repeatedly verifying credentials with the server, the system issues a token that proves the user's identity.

What is JWT?

JWT (JSON Web Token) is a compact, URL-safe token used for securely transmitting information between parties.

JWTs are commonly used for:

JWTs are stateless, meaning the server does not need to store session data.

All required information is inside the token.

Stateless vs Stateful Authentication

Before JWTs, systems used session-based authentication.

Session-Based Authentication

Problems:

JWT Authentication (Stateless)

Benefits:

JWT Structure

A JWT has three parts separated by dots:

HEADER.PAYLOAD.SIGNATURE

Example JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIn0
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

JWT Components

1 Header

Contains metadata about the token.

Example:

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

Fields:

Common algorithms:

2 Payload

Contains claims (data) about the user.

Example:

{
 "userId": 123,
 "role": "admin",
 "exp": 1716239022
}

Claims fall into three categories.

Registered Claims

Standard fields defined by JWT specification.

Public Claims

Custom claims defined by developers.

Example:

{
 "userId": "abc123",
 "plan": "premium"
}

Private Claims

Used internally between services.

Example:

{
 "permissions": ["read", "write"]
}

3 Signature

The signature ensures the token has not been tampered with.

Signature generation:

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

Example:

If the payload changes, the signature becomes invalid.

JWT Authentication Flow

Complete login flow:

Authorization Header

JWTs are typically sent using the Authorization header.

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example JWT Authentication (JavaScript)

Generating JWT

const jwt = require("jsonwebtoken");
 
const token = jwt.sign(
  { userId: 123, role: "admin" },
  "secret_key",
  { expiresIn: "1h" }
);
 
console.log(token);

Verifying JWT

const jwt = require("jsonwebtoken");
 
function authenticate(req, res, next) {
 
 const authHeader = req.headers.authorization;
 
 if (!authHeader) {
   return res.status(401).send("No token");
 }
 
 const token = authHeader.split(" ")[1];
 
 try {
   const decoded = jwt.verify(token, "secret_key");
   req.user = decoded;
   next();
 } catch (err) {
   res.status(401).send("Invalid token");
 }
 
}

Access Token vs Refresh Token

JWT authentication often uses two tokens.

Token Lifecycle

Why Refresh Tokens Exist

Access tokens should be short-lived.

Example:

Benefits:

Token Storage Options

Where should JWTs be stored?

Local Storage

localStorage.setItem("token", jwt);

Advantages:

• Easy to use

Disadvantages:

• Vulnerable to XSS attacks

HTTP-only Cookies

Safer option.

Set-Cookie: token=jwt; HttpOnly

Advantages:

JWT in Microservices

JWT works well in distributed systems.

Instead of each service querying a database, services verify tokens independently.

Each service:

• Verifies JWT signature
• Extracts user identity
• Applies authorization rules

No central session store required.

JWT Security Considerations

JWT misuse can lead to serious security vulnerabilities.

1 Never Store Sensitive Data

JWT payload is not encrypted.

Anyone can decode it.

Bad example:

{
 "password": "123456"
}

2 Use Short Expiration

Example:

Access token = 15 minutes

3 Use HTTPS

Tokens must always travel via HTTPS.

Otherwise they can be intercepted.

4 Rotate Secrets

Secret keys must be rotated periodically.

5 Blacklist Compromised Tokens

For logout functionality:

• Maintain token blacklist
• Or reduce expiration time

JWT vs Session Authentication

When to Use JWT

JWT is ideal for:

Avoid JWT when:

• Frequent logout needed
• Token revocation required
• Sensitive data involved

Real World Example Architecture

Example: Large-scale application.

Authentication steps:

1. User logs in
2. AuthService issues JWT
3. API Gateway validates token
4. Requests forwarded to services

JWT Best Practices

Key Takeaways

JWT is one of the most widely used authentication mechanisms in modern systems.

It enables:

• Stateless authentication
• Scalable microservices
• Efficient API security
• Reduced database lookups

However, proper implementation is crucial to avoid security vulnerabilities.

Understanding JWT deeply is essential for designing secure large-scale distributed systems.