Web Security

The Complete Guide to JSON Web Tokens (JWT) for Modern Developers

Written by Rishabh

Security & Encryption Specialist, ARGAMING SCRIPTS

In the early days of the web, managing user state was simple. You had one server, one database, and a monolithic application. When a user logged in, the server created a "session" in its memory and handed the user a "Session ID" via a cookie. Every time the user came back, the server looked up that ID in its memory, found the user, and said, "Ah, welcome back, Dave."

But then the web grew up. We moved to distributed systems, microservices, and massive clusters of servers. Suddenly, "Dave" might hit Server A for his login but hit Server B for his profile picture. If Server B doesn't share memory with Server A, it has no idea who Dave is.

Enter JSON Web Tokens (JWT). JWTs changed the game by moving the state from the server's memory into the token itself. In this guide, we’re going to dissect what JWTs are, why they’ve become the industry standard, and how to use them without accidentally leaving the door open for hackers.

What is a JSON Web Token?

At its core, a JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

The "self-contained" part is the magic. A JWT carries all the information a server needs to identify a user and their permissions, meaning the server doesn't need to query a database every single time a request comes in.

The Anatomy of a JWT

A JWT is composed of three parts separated by dots (.):

Header
Payload
Signature

It looks like this: xxxxx.yyyyy.zzzzz

1. The Header

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

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

2. The Payload

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

Registered claims: Predefined claims like iss (issuer), exp (expiration time), sub (subject), and aud (audience).
Public claims: These can be defined at will by those using JWTs but should be collision-resistant.
Private claims: Custom claims created to share information between parties that agree on using them (e.g., userId or role).

{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"exp": 1713456000
}

3. The Signature

To create the signature part, you take the encoded header, the encoded payload, a secret, and the algorithm specified in the header to sign it. The mathematical representation of the signature for HMAC SHA256 looks like this:

$$Signature = HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)$$

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

How the JWT Flow Works

Understanding the lifecycle of a JWT is crucial for implementation. Unlike session cookies, the server does not "hold onto" the token.

Authentication: The user sends their credentials (username/password) to the server.
Creation: The server validates the credentials and creates a JWT signed with a private secret or key.
Transmission: The server sends the JWT back to the client.
Storage: The client stores the JWT (usually in localStorage or an HttpOnly cookie).
Authorization: For every subsequent request, the client sends the JWT in the Authorization header using the Bearer schema:
Authorization: Bearer <token>
Verification: The server receives the token, checks the signature against its secret key, and if it matches, the user is authenticated.

JWT vs. Traditional Sessions

Why bother with JWTs when sessions have worked for decades? It comes down to Scalability.

Feature	Session-Based Auth	JWT-Based Auth
Storage	Stored on Server (RAM/Redis)	Stored on Client
Scalability	Hard (requires sticky sessions or shared DB)	Easy (Stateless)
Payload	Small (just an ID)	Larger (contains user data)
Revocation	Easy (delete from DB)	Hard (requires blacklisting)
CORS	Can be tricky	Native support

Why Developers Love (and Hate) JWTs

The Pros

Statelessness: This is the big one. Your API servers don't need to keep track of who is logged in. This makes horizontal scaling a breeze.
Mobile Friendly: Cookies are notoriously difficult to manage in native mobile apps. JWTs are just strings, making them incredibly easy to pass around.
Decoupling: You can have one dedicated "Auth Service" that issues tokens, and ten other "Microservices" that simply verify the tokens without ever talking to the Auth Service again.

The Cons

Size: Because JWTs contain claims and metadata, they can become quite large, adding overhead to every single HTTP request.
Revocation: Since the server doesn't check a database, you can't easily "log a user out" instantly if their token is stolen. The token remains valid until it expires.
Security Hazards: If you don't use HTTPS, your token can be intercepted. If you store it in localStorage, you are vulnerable to Cross-Site Scripting (XSS).

Security Best Practices for Modern Developers

Using JWTs incorrectly is often worse than not using them at all. Here is how to keep your implementation battle-hardened.

1. Never Put Sensitive Data in the Payload

Remember: JWTs are signed, not encrypted (by default). Anyone who gets a hold of your token can Base64-decode the payload and see exactly what's inside. Never put passwords, credit card numbers, or social security numbers in a JWT payload.

2. Use Short Expiration Times

To mitigate the "Revocation Problem," keep your access tokens short-lived (e.g., 15 minutes). Use Refresh Tokens to allow users to stay logged in without re-entering credentials.

3. Use HttpOnly and Secure Cookies

While localStorage is easy to use, it's accessible by any JavaScript running on your page. If a malicious script (XSS) gets in, your JWT is gone. Storing the JWT in a cookie with the HttpOnly flag prevents JavaScript from reading it, and the Secure flag ensures it’s only sent over HTTPS.

4. Validate the `alg` Header

One of the most famous JWT vulnerabilities involves changing the algorithm in the header to "none". A poorly configured server might see alg: none, skip the signature verification, and treat the token as valid. Always explicitly define which algorithms your server allows.

5. Rotate Your Secrets

Your JWT is only as secure as your secret key. If your secret is password123, a brute-force attack will crack your tokens in seconds. Use long, random strings and rotate them periodically.

Choosing the Right Algorithm: HS256 vs. RS256

When setting up your JWT implementation, you'll likely choose between these two:

HS256 (Symmetric): The same secret key is used to both sign and verify the token. This is great for internal applications where only one party is handling the tokens.
RS256 (Asymmetric): Uses a Private Key to sign the token and a Public Key to verify it. This is the gold standard for modern web apps. It allows your "Auth Service" to sign tokens, while your "Resource Services" can verify them using only the public key—never needing access to the private signing key.

Conclusion: Are JWTs Right for You?

JWTs are not a magic bullet. If you are building a simple, small-scale web app where all requests happen on a single domain, traditional sessions might actually be easier and safer.

However, if you are building a SPA (Single Page Application), a Mobile App, or a Microservices Architecture, JWTs are almost certainly the right tool for the job. They provide the flexibility and scalability that modern development demands.

The key to JWT success is respecting the "stateless" nature of the token while being paranoid about its storage. Keep them short, keep them signed, and keep your secrets secret.

Expert Tip: Always use established libraries like jsonwebtoken (Node.js), PyJWT (Python), or ruby-jwt (Ruby) rather than trying to manually encode and sign tokens yourself. Cryptography is hard; let the experts handle the heavy lifting.