JWT structure and flow in Rest API - Deep Dive

Overview - JWT structure and flow

What is it?

JWT stands for JSON Web Token. It is a compact way to securely transmit information between two parties as a JSON object. The token has three parts: header, payload, and signature, which together ensure the data is trustworthy and untampered. JWTs are often used to manage user authentication in web applications.

Why it matters

Without JWTs, web applications would struggle to securely identify users across multiple requests without storing session data on the server. JWTs solve this by embedding user information and verification in a token that travels with each request. This makes apps faster, scalable, and easier to maintain, improving user experience and security.

Where it fits

Before learning JWTs, you should understand HTTP basics, REST APIs, and how authentication works generally. After JWTs, you can explore OAuth, OpenID Connect, and advanced security practices for APIs and web apps.

Mental Model

Core Idea

A JWT is like a sealed envelope containing user info that anyone can carry, but only the server can verify it wasn’t opened or changed.

Think of it like...

Imagine sending a letter in a sealed envelope with a wax stamp. The letter is the payload (user data), the envelope is the header (metadata), and the wax stamp is the signature that proves the letter is authentic and untouched.

┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│   Header      │ │   Payload     │ │  Signature    │
│ (metadata)    │ │ (user data)   │ │ (verification)│
└──────┬────────┘ └──────┬────────┘ └──────┬────────┘
       │                 │                 │
       └───── Base64Url encoded ──────────┘
                 │
          Joined by dots '.'
                 │
          JWT Token string

Build-Up - 7 Steps

1

Foundation

Understanding JWT Basic Parts

Concept: JWT consists of three parts: header, payload, and signature, each serving a specific role.

The header tells what type of token it is and the algorithm used to sign it. The payload contains the actual data like user ID or permissions. The signature is created by combining the header and payload with a secret key to ensure the token is valid and unchanged.

Result

You can identify the three parts of a JWT and understand their roles.

Knowing the three parts helps you see how JWTs carry data securely and why each part is necessary.

2

Foundation

Base64Url Encoding Explained

Concept: JWT parts are encoded using Base64Url to make them safe to send in URLs and HTTP headers.

Base64Url encoding converts binary data into text using letters, numbers, and a few symbols, but replaces '+' and '/' with URL-safe characters. This ensures the JWT can travel safely over the internet without breaking.

Result

You understand why JWT parts look like random letters and numbers and how they are safely transmitted.

Recognizing Base64Url encoding clarifies why JWTs are compact and URL-friendly.

3

Intermediate

How JWT Signature Works

🤔Before reading on: Do you think the signature encrypts the data or just verifies it? Commit to your answer.

Concept: The signature is a hash created from the header and payload plus a secret key, used to verify the token's integrity.

The server uses a secret key and a hashing algorithm (like HMAC SHA256) to create a signature from the header and payload. When a token is received, the server recalculates the signature and compares it to the one in the token. If they match, the token is valid and untampered.

Result

You know how the server checks if a JWT is authentic and unchanged.

Understanding the signature mechanism is key to trusting JWTs and preventing forgery.

4

Intermediate

JWT Flow in Authentication

🤔Before reading on: Does the server store JWTs to track users or rely on the token itself? Commit to your answer.

Concept: JWTs enable stateless authentication by carrying user info in the token, so the server doesn't need to store session data.

When a user logs in, the server creates a JWT with user info and sends it to the client. The client stores it (usually in local storage or cookies) and sends it with each request. The server verifies the token and grants access without storing session info.

Result

You see how JWTs simplify authentication by removing server-side session storage.

Knowing JWT flow helps you design scalable and efficient authentication systems.

5

Intermediate

Common JWT Claims and Their Roles

Concept: JWT payload contains claims—standard or custom pieces of information about the user or token.

Standard claims include 'iss' (issuer), 'sub' (subject), 'exp' (expiration time), and 'iat' (issued at). Custom claims can hold user roles or permissions. These claims help servers decide who the user is and what they can do.

Result

You can read and use JWT claims to control access and token validity.

Understanding claims lets you customize JWTs for your app’s security needs.

6

Advanced

Security Risks and Best Practices

🤔Before reading on: Is it safe to store JWTs in local storage or cookies? Commit to your answer.

Concept: JWTs have security risks like token theft or misuse, so best practices are essential.

Storing JWTs in local storage exposes them to cross-site scripting (XSS) attacks. Using HttpOnly, Secure cookies reduces this risk. Also, tokens should have short expiration times and be refreshed securely. Avoid putting sensitive info in payload since JWTs are only base64 encoded, not encrypted.

Result

You know how to protect JWTs and avoid common security pitfalls.

Recognizing JWT risks helps you build safer authentication systems.

7

Expert

JWT Internals and Algorithm Choices

🤔Before reading on: Do all JWT algorithms provide the same security level? Commit to your answer.

Concept: JWT supports multiple signing algorithms with different security properties and performance tradeoffs.

Common algorithms include HS256 (HMAC with SHA-256) which uses a shared secret, and RS256 (RSA with SHA-256) which uses public/private keys. RS256 allows token verification without exposing the private key, useful in distributed systems. Choosing the right algorithm affects security and scalability.

Result

You understand how algorithm choice impacts JWT security and architecture.

Knowing algorithm differences prevents weak security setups and supports advanced system designs.

Under the Hood

JWTs are created by encoding the header and payload as JSON, then Base64Url encoding them. The signature is generated by hashing the encoded header and payload with a secret key using a cryptographic algorithm. When verifying, the server repeats this process and compares signatures. This ensures the token is authentic and unchanged without needing server-side storage.

Why designed this way?

JWT was designed to be compact, URL-safe, and stateless to support scalable web applications. Using JSON makes it easy to include structured data. The signature mechanism balances security with performance, allowing servers to verify tokens quickly without database lookups. Alternatives like server sessions require storage and reduce scalability.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Header      │──────▶│ Base64Url Enc │──────▶│               │
└───────────────┘       └───────────────┘       │               │
                                               │               │
┌───────────────┐       ┌───────────────┐       │               │
│   Payload     │──────▶│ Base64Url Enc │──────▶│ Concatenate   │─────┐
└───────────────┘       └───────────────┘       │ Header.Payload│     │
                                               │               │     │
                                               └───────────────┘     │
                                                                     │
┌───────────────┐       ┌───────────────┐       ┌───────────────┐     │
│ Secret Key    │──────▶│ Hash Function │──────▶│ Signature     │◀────┘
└───────────────┘       └───────────────┘       └───────────────┘

Final JWT = Base64Url(Header).Base64Url(Payload).Signature

Myth Busters - 4 Common Misconceptions

Quick: Does the JWT signature encrypt the payload so no one can read it? Commit yes or no.

Common Belief: The JWT signature encrypts the payload, so the data inside is secret.

Reality: The signature only verifies the token’s integrity; the payload is base64 encoded and easily readable by anyone.

Why it matters: Assuming payload is secret can lead to exposing sensitive data unintentionally.

Quick: Does the server need to store JWTs to validate them? Commit yes or no.

Common Belief: The server must store JWTs to track active sessions and validate tokens.

Reality: JWTs are stateless; the server validates tokens using the signature without storing them.

Why it matters: Storing JWTs defeats their purpose and can cause scalability issues.

Quick: Is it safe to store JWTs in local storage? Commit yes or no.

Common Belief: Storing JWTs in local storage is safe and convenient for client apps.

Reality: Local storage is vulnerable to XSS attacks; storing JWTs in HttpOnly cookies is safer.

Why it matters: Improper storage can lead to token theft and account compromise.

Quick: Are all JWT signing algorithms equally secure? Commit yes or no.

Common Belief: All JWT algorithms provide the same level of security.

Reality: Algorithms differ; symmetric keys (HS256) require shared secrets, while asymmetric keys (RS256) use public/private keys with different security properties.

Why it matters: Choosing weak or inappropriate algorithms can expose your system to attacks.

Expert Zone

1

JWT expiration ('exp' claim) is critical but often ignored, leading to tokens valid forever and security risks.

2

Using asymmetric algorithms (like RS256) allows token verification without exposing private keys, enabling distributed verification.

3

JWTs can be revoked only by additional mechanisms since they are stateless; this requires token blacklists or short lifetimes.

When NOT to use

JWTs are not ideal when you need immediate token revocation or store sensitive data requiring encryption. In such cases, traditional server sessions or encrypted tokens (like PASETO) may be better.

Production Patterns

In real systems, JWTs are used with refresh tokens to maintain sessions securely. They are often combined with scopes and roles in claims for fine-grained access control. Many APIs use JWTs for stateless authentication, enabling horizontal scaling without session storage.

Connections

OAuth 2.0

JWTs are often used as access tokens within OAuth 2.0 flows.

Understanding JWTs helps grasp how OAuth securely delegates access without sharing passwords.

Digital Signatures

JWT signatures are a form of digital signature ensuring data integrity and authenticity.

Knowing digital signatures clarifies why JWTs can be trusted without server storage.

Postal Mail System

JWT flow resembles sending sealed letters with stamps to verify authenticity.

This cross-domain connection shows how trust and verification work in communication systems.

Common Pitfalls

#1 Storing JWTs in local storage without protection.

Wrong approach:

localStorage.setItem('token', jwtToken);

Correct approach:

Set JWT in HttpOnly, Secure cookie to prevent JavaScript access.

Root cause:

Misunderstanding that local storage is vulnerable to cross-site scripting attacks.

#2 Putting sensitive data like passwords inside JWT payload.

Wrong approach:

{"sub":"user123", "password":"secret"}

Correct approach:

{"sub":"user123"} // Keep sensitive data out of JWT payload

Root cause:

Believing JWT payload is encrypted rather than just encoded.

#3 Not setting expiration on JWTs, making them valid forever.

Wrong approach:

{"sub":"user123"} // no 'exp' claim

Correct approach:

{"sub":"user123", "exp": 1680000000} // set expiration timestamp

Root cause:

Ignoring token lifetime leads to security risks if tokens are stolen.

Key Takeaways

JWTs are compact tokens with three parts: header, payload, and signature, used to securely transmit user info.

The signature verifies the token’s integrity but does not encrypt the payload, which remains readable.

JWTs enable stateless authentication, removing the need for server-side session storage and improving scalability.

Proper storage and expiration of JWTs are critical to prevent security vulnerabilities like token theft.

Choosing the right signing algorithm and understanding JWT flow are essential for building secure and efficient web applications.