JWT structure (header, payload, signature) in Spring Boot - Deep Dive

Overview - JWT structure (header, payload, signature)

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. A JWT has three parts: header, payload, and signature. Each part has a specific role in ensuring the token is trustworthy and contains useful data.

Why it matters

JWTs solve the problem of safely sharing user identity and claims without needing to store session data on the server. Without JWTs, systems would rely on server memory or databases for sessions, which can slow down apps and make scaling harder. JWTs let apps verify users quickly and securely, improving performance and user experience.

Where it fits

Before learning JWT structure, you should understand basic web security concepts like authentication and authorization. After mastering JWTs, you can learn how to implement them in Spring Boot for secure APIs and explore advanced topics like token expiration and refresh tokens.

Mental Model

Core Idea

A JWT is like a sealed envelope containing a message (payload) with a label (header) and a wax seal (signature) that proves it hasn't been tampered with.

Think of it like...

Imagine sending a letter in an envelope. The envelope's front shows who sent it and how it was sealed (header). Inside is the letter with the message (payload). The wax seal on the envelope (signature) proves the letter is genuine and unopened.

┌─────────────┐ ┌─────────────┐ ┌───────────────┐
│   Header    │ │   Payload   │ │  Signature    │
│ (metadata)  │ │ (claims)    │ │ (verification)│
└─────┬───────┘ └─────┬───────┘ └──────┬────────┘
      │               │               │
      └───── Base64 ──┴──── Base64 ───┘
             Encoded and joined by dots
             Example: header.payload.signature

Build-Up - 7 Steps

1

Foundation

JWT basic parts explained

Concept: JWT consists of three parts: header, payload, and signature, each encoded separately.

The header is a small JSON object that tells what type of token it is and which algorithm is used to sign it. The payload contains the actual data or claims, like user ID or roles. The signature is created by combining the encoded header and payload with a secret key, ensuring the token is authentic.

Result

You understand the three parts and their roles in a JWT.

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

2

Foundation

Base64 encoding in JWT

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

Each part (header, payload, signature) is converted from JSON or binary data into a Base64Url string. This encoding uses letters, numbers, and a few symbols safe for web transport. The three encoded parts are joined by dots to form the JWT string.

Result

You can recognize and decode JWT parts from their Base64Url strings.

Understanding Base64Url encoding explains why JWTs look like random strings but can be decoded easily.

3

Intermediate

Header content and algorithms

🤔Before reading on: Do you think the header contains user data or only metadata? Commit to your answer.

Concept: The header contains metadata about the token, especially the signing algorithm used.

A typical header looks like {"alg":"HS256","typ":"JWT"}. 'alg' tells which cryptographic algorithm signs the token (e.g., HS256 means HMAC SHA-256). 'typ' usually is 'JWT' to identify the token type. This helps the receiver know how to verify the signature.

Result

You can read and understand the header's role in token verification.

Knowing the header's metadata guides how the token is checked for authenticity.

4

Intermediate

Payload claims and their meaning

🤔Before reading on: Do you think the payload is encrypted or just encoded? Commit to your answer.

Concept: The payload contains claims, which are statements about an entity (usually the user) and additional data.

Claims can be registered (standard), public, or private. Registered claims include 'iss' (issuer), 'exp' (expiration), and 'sub' (subject). Public claims are agreed upon by parties, and private claims are custom data. The payload is only Base64Url encoded, not encrypted, so anyone can read it but cannot trust it without verifying the signature.

Result

You understand what data JWTs carry and their trust limitations.

Recognizing that payload is not secret prevents security mistakes like storing sensitive info without encryption.

5

Intermediate

Signature creation and verification

🤔Before reading on: Is the signature created from the payload alone or from both header and payload? Commit to your answer.

Concept: The signature is created by signing the combined encoded header and payload with a secret key using the specified algorithm.

To create the signature, the system takes the Base64Url encoded header and payload, joins them with a dot, and applies the signing algorithm with a secret key. This signature ensures the token was issued by a trusted party and has not been altered. When verifying, the receiver repeats this process and compares the signature.

Result

You understand how JWTs ensure data integrity and authenticity.

Knowing the signature depends on both header and payload explains why changing any part invalidates the token.

6

Advanced

JWT structure in Spring Boot usage

🤔Before reading on: Do you think Spring Boot automatically creates JWTs or requires explicit code? Commit to your answer.

Concept: Spring Boot uses JWTs by creating and parsing tokens with libraries, respecting the header, payload, and signature structure.

In Spring Boot, libraries like jjwt or spring-security-oauth2-jose handle JWT creation and validation. Developers build the header and payload as Java objects, then sign them with a secret key or private key. The framework encodes and joins the parts into a JWT string. On receiving a token, Spring Boot decodes and verifies the signature before trusting the payload data.

Result

You see how JWT structure maps to Spring Boot code and security flow.

Understanding JWT internals helps debug token issues and customize security in Spring Boot.

7

Expert

Security pitfalls in JWT structure

🤔Before reading on: Can a JWT be trusted if only the payload is checked without verifying the signature? Commit to your answer.

Concept: JWTs must always verify the signature; otherwise, attackers can forge tokens by changing the payload or header.

Some systems mistakenly trust the payload without signature verification, exposing security holes. Also, weak signing algorithms or leaked keys can compromise JWTs. Experts carefully choose algorithms, rotate keys, and validate tokens fully. They also understand that JWTs are not encrypted by default, so sensitive data should not be stored in the payload.

Result

You grasp critical security practices around JWT structure.

Knowing the limits of JWT trust prevents severe security vulnerabilities in real applications.

Under the Hood

JWTs work by encoding JSON objects into Base64Url strings and signing them with cryptographic algorithms. The signature is generated by applying a hash function combined with a secret key or private key to the header and payload. This signature ensures the token's integrity and authenticity. When a JWT is received, the system decodes the header and payload, then recalculates the signature to verify it matches. If it does, the token is trusted; otherwise, it is rejected.

Why designed this way?

JWT was designed to be compact, URL-safe, and stateless to support scalable web applications. Using Base64Url encoding makes tokens easy to pass in HTTP headers or URLs. Separating header, payload, and signature allows flexible algorithms and clear data structure. The signature mechanism avoids server-side session storage, improving performance and scalability. Alternatives like opaque tokens require server storage, which limits scalability.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│   Header      │      │   Payload     │      │  Signature    │
│ JSON metadata │      │ JSON claims   │      │ Cryptographic │
│ Base64Url     │      │ Base64Url     │      │ signature     │
└──────┬────────┘      └──────┬────────┘      └──────┬────────┘
       │                      │                      │
       └───── Join with '.' ──┴──── Join with '.' ───┘
                      ↓
             JWT string: header.payload.signature
                      ↓
          Verification by recomputing signature
                      ↓
          Accept if signature matches, else reject

Myth Busters - 4 Common Misconceptions

Quick: Is the JWT payload encrypted by default? Commit to yes or no.

Common Belief: Many believe the JWT payload is encrypted and private.

Reality: The payload is only Base64Url encoded, not encrypted, so anyone can decode and read it.

Why it matters: Storing sensitive data in the payload without encryption risks exposure to attackers or anyone with the token.

Quick: Can you trust a JWT payload without verifying its signature? Commit to yes or no.

Common Belief: Some think the payload can be trusted as is without checking the signature.

Reality: Without verifying the signature, the payload can be tampered with and is not trustworthy.

Why it matters: Skipping signature verification allows attackers to forge tokens and gain unauthorized access.

Quick: Does the JWT header contain user data? Commit to yes or no.

Common Belief: People often think the header contains user information or claims.

Reality: The header only contains metadata about the token type and signing algorithm, not user data.

Why it matters: Misunderstanding header content can lead to incorrect token parsing or security assumptions.

Quick: Is the JWT signature created from the payload alone? Commit to yes or no.

Common Belief: Some believe the signature signs only the payload part.

Reality: The signature signs both the encoded header and payload together.

Why it matters: Knowing this prevents attacks that modify the header or payload separately without invalidating the signature.

Expert Zone

1

Some JWT libraries allow 'none' as an algorithm, meaning no signature; experts avoid this to prevent security holes.

2

JWTs can use asymmetric keys (RSA, ECDSA) for signature, allowing public verification without exposing private keys.

3

The order and exact encoding of header and payload affect signature; even whitespace changes can invalidate tokens.

When NOT to use

JWTs are not suitable when you need to store highly sensitive data that must remain confidential; use encrypted tokens or sessions instead. Also, for short-lived or single-use tokens, opaque tokens with server-side storage may be safer.

Production Patterns

In production, JWTs are used for stateless authentication in REST APIs, often with short expiration times and refresh tokens. They are combined with HTTPS to protect tokens in transit. Key rotation and revocation strategies are implemented to maintain security.

Connections

Digital Signatures

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

Understanding digital signatures helps grasp how JWTs prevent tampering and verify the sender.

Session Management

JWTs provide a stateless alternative to traditional server-side session management.

Knowing session management clarifies why JWTs improve scalability and reduce server load.

Postal Mail Security

JWT structure parallels how sealed letters ensure message authenticity and privacy.

Recognizing this connection deepens understanding of token trust and message protection.

Common Pitfalls

#1 Trusting JWT payload without signature verification

Wrong approach:

String token = "header.payload.signature";
// decode payload and use data without verifying signature

Correct approach:

Use JWT library to parse token and verify signature before trusting payload data

Root cause:

Misunderstanding that encoding is not encryption and skipping signature verification.

#2 Storing sensitive data in JWT payload

Wrong approach:

payload = {"password":"secret123", "ssn":"123-45-6789"}; // put directly in JWT

Correct approach:

Store only non-sensitive claims in payload; keep secrets on server or encrypt token

Root cause:

Belief that JWT payload is private because it is encoded.

#3 Using weak or no signing algorithm

Wrong approach:

header = {"alg":"none", "typ":"JWT"}; // no signature

Correct approach:

Use strong algorithms like HS256 or RS256 and never accept 'none' algorithm

Root cause:

Lack of awareness about security risks of unsigned tokens.

Key Takeaways

A JWT is made of three parts: header, payload, and signature, each serving a clear purpose.

The payload is only encoded, not encrypted, so never put sensitive data inside without protection.

The signature ensures the token is authentic and untampered; always verify it before trusting the token.

JWTs enable stateless, scalable authentication but require careful handling of keys and algorithms.

Understanding JWT internals helps build secure applications and avoid common security mistakes.