JWT Tokens Explained: What Every Developer Should Know

What is a JWT?

A JSON Web Token (JWT) is a compact, URL-safe token used to transmit claims between two parties. It is commonly used for authentication and authorization in web applications.

JWT Structure

A JWT has three parts separated by dots:

header.payload.signature

Header

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

Specifies the signing algorithm and token type.

Payload

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622
}

Contains the claims (data). Standard claims include:

• sub: subject (user ID)
• iat: issued at (timestamp)
• exp: expiration (timestamp)
• iss: issuer
• aud: audience

Signature

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

Verifies the token has not been tampered with.

How JWT Authentication Works

1. User logs in with credentials

2. Server verifies credentials, creates JWT

3. Server sends JWT to client

4. Client stores JWT (usually in memory or httpOnly cookie)

5. Client sends JWT with each request (Authorization header)

6. Server validates JWT signature and checks expiration

7. Server processes the request if valid

HS256 vs RS256

HS256 (symmetric)

• Same secret key for signing and verification
• Simpler to implement
• Both parties need the secret
• Good for: single-server setups

RS256 (asymmetric)

• Private key signs, public key verifies
• More complex but more secure
• Only auth server needs the private key
• Good for: microservices, third-party verification

Security Best Practices

Do

• Set short expiration times (15-60 minutes for access tokens)
• Use refresh tokens for long sessions
• Store in httpOnly cookies (not localStorage)
• Validate ALL claims (exp, iss, aud)
• Use RS256 for distributed systems

Do Not

• Store sensitive data in the payload (it is only base64-encoded, not encrypted)
• Use JWT for session management (use server-side sessions instead)
• Set "alg": "none" - this disables signature verification
• Store in localStorage (vulnerable to XSS)
• Create tokens that never expire

Common JWT Pitfalls

1. Algorithm confusion attack

If your server accepts both HS256 and RS256, an attacker can change the algorithm header and sign with the public key.

Fix: Always validate the algorithm server-side. Never let the token dictate which algorithm to use. 2. Missing expiration

Tokens without exp claim live forever.

Fix: Always set expiration. Use short-lived access tokens + refresh tokens. 3. Secret key weakness

Using "secret" or "password" as your HMAC key.

Fix: Use at least 256 bits of entropy. Generate with a cryptographic random generator.

Refresh Token Pattern

1. Login -> Access Token (15 min) + Refresh Token (7 days)
2. API call -> Send Access Token
3. Access Token expired -> Send Refresh Token to /refresh
4. Server validates Refresh Token -> New Access Token
5. Refresh Token expired -> User must log in again

Developer Tools

• JWT Decoder - decode and inspect JWT tokens instantly
• Base64 Encoder/Decoder - encode and decode base64 strings
• JSON Formatter - format JWT payloads for readability
• Hash Generator - generate SHA hashes for verification