JWT Explained for Beginners: A Complete Guide

What is a JWT?

JSON Web Token (JWT) is a compact, self contained and secure way to exchange information between two parties using a JSON object.

Imagine you're visiting an all-inclusive resort. When you check in, you get a special wristband. This wristband proves to the staff that you're a guest and grants you access to everything—the pool, the buffet, the evening shows. You don't need to show your ID every time; the wristband is enough.

A JWT is like that wristband. It's a compact, self-contained token that allows two parties to securely exchange information. Once a user logs in, the server creates a JWT and sends it to the client. The client then includes this token with every subsequent request to prove its identity.

Structure of a JWT

JWT consists of three parts, separated by dots (.):

• Header: Contains the token type and the signing algorithm.
• Payload: Contains the claims (user data and metadata).
• Signature: Verifies the token hasn't been altered.

So, a JWT looks like this: hhh.ppp.sss where hhh is the header, ppp is the payload, and sss is the signature.

1. Header

The header typically consists of two parts: the token type, which is JWT, and the signing algorithm being used, such as HMAC SHA256 or RSA.

Example Header:

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

This JSON is then Base64Url encoded to form the first part of the JWT.

2. Payload

The payload contains the "claims," which are statements about an entity (typically, the user) and additional data. There are three types of claims:

• Registered Claims: These are predefined claims like iss (issuer), exp (expiration time), and sub (subject).
• Public Claims: These are custom claims that are defined in a public registry to avoid collisions.
• Private Claims: These are custom claims created to share information between parties that agree on using them.

Example Payload:

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

The payload is also Base64Url encoded to form the second part of the JWT.

3. Signature

To create the signature, you take the encoded header, the encoded payload, a secret key, and sign it with the algorithm specified in the header.

Example Signature:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  your-256-bit-secret
)

The signature is crucial for security. It verifies that the sender of the JWT is who it says it is and ensures that the message wasn't changed along the way. If some one tampers with the token, the signature will be invalid and the server will reject the request. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA or ECDSA.

How JWT Authentication Works

Here's a typical authentication flow:

1. 1. Login: The user enters their credentials (e.g., email and password).
2. 2. Verification: The server validates the credentials.
3. 3. Token Generation: If the credentials are correct, the server generates a JWT (and often a refresh token) and sends it back to the client.
4. 4. Storage: The client stores the token(s) securely (e.g., in an HttpOnly cookie or localStorage).
5. 5. Authorization: For every request to a protected resource, the client sends the JWT in the Authorization header, typically using the Bearer schema: Authorization: Bearer <token>.
6. 6. Server Validation: The server receives the request, extracts the token, and verifies its signature. If the token is valid, the server processes the request; otherwise, it sends back a 401 Unauthorized error.

Different Types of Tokens

In modern authentication systems, you'll often encounter two main types of tokens working together:

1. 1. Access Tokens: These are short-lived tokens (e.g., valid for 15 minutes) that are sent with every request to access a protected resource. Their short lifespan reduces the risk if a token is compromised.
2. 2. Refresh Tokens: These are long-lived tokens (e.g., valid for 7 days) that are used to generate new access tokens. When an access token expires, the client sends the refresh token to a special endpoint to get a new one without forcing the user to log in again.

Want to see a full implementation in Java with Spring Security?
Check out JWT Authentication with Spring 6 Security: Complete Guide for hands-on code and step-by-step building of secure authentication using JWTs in a real-world Spring Boot application.