Understanding JWT Tokens:
Complete Developer Guide

1. What is a JWT Token?

JWT (JSON Web Token) is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. JWTs are digitally signed, so the information can be verified and trusted.

Key Characteristics of JWT:

• Compact: Small size allows transmission in URLs, headers, or POST parameters
• Self-contained: Contains all the information needed about the user
• Stateless: Server doesn't need to store session data
• Verifiable: Digital signature ensures data integrity

Common Use Cases:

• Authentication: After login, each request includes the JWT for access control
• Information Exchange: Securely transmit data between parties
• Authorization: Determine what resources a user can access
• Single Sign-On (SSO): Share authentication across multiple domains

2. JWT Structure (Header, Payload, Signature)

A JWT consists of three parts separated by dots (.): xxxxx.yyyyy.zzzzz

{
  "alg": "HS256",    // Signing algorithm
  "typ": "JWT"       // Token type
}

{
  "sub": "1234567890",      // Subject (user ID)
  "name": "John Doe",       // Custom claim
  "admin": true,            // Custom claim
  "iat": 1516239022,        // Issued at
  "exp": 1516242622         // Expiration time
}

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

3. JWT Authentication Flow

Request Header Format:

// HTTP Authorization Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIi4uLn0.signature

Refresh Token Flow:

For better security, use short-lived access tokens with longer-lived refresh tokens:

• Access Token: Short-lived (5-15 minutes), used for API requests
• Refresh Token: Long-lived (days/weeks), used to get new access tokens

4. Standard JWT Claims Explained

Custom Claims:

You can add any custom claims for your application:

{
  "sub": "user_123",
  "email": "john@example.com",
  "role": "admin",
  "permissions": ["read", "write", "delete"],
  "organization_id": "org_456"
}

5. Signing Algorithms (HS256, RS256, ES256)

Algorithm Comparison:

6. Implementation in Different Languages

JavaScript (Node.js with jsonwebtoken)

const jwt = require('jsonwebtoken');

// Secret key (use environment variable in production!)
const SECRET = process.env.JWT_SECRET;

// Create a token
function createToken(user) {
    const payload = {
        sub: user.id,
        email: user.email,
        role: user.role
    };
    
    return jwt.sign(payload, SECRET, {
        expiresIn: '15m',    // Short-lived access token
        issuer: 'myapp.com',
        audience: 'myapp.com'
    });
}

// Verify a token
function verifyToken(token) {
    try {
        const decoded = jwt.verify(token, SECRET, {
            issuer: 'myapp.com',
            audience: 'myapp.com'
        });
        return { valid: true, payload: decoded };
    } catch (err) {
        return { valid: false, error: err.message };
    }
}

// Express middleware
function authMiddleware(req, res, next) {
    const authHeader = req.headers.authorization;
    if (!authHeader?.startsWith('Bearer ')) {
        return res.status(401).json({ error: 'No token provided' });
    }
    
    const token = authHeader.split(' ')[1];
    const result = verifyToken(token);
    
    if (!result.valid) {
        return res.status(401).json({ error: result.error });
    }
    
    req.user = result.payload;
    next();
}

Python (PyJWT)

import jwt
from datetime import datetime, timedelta
import os

SECRET = os.environ.get('JWT_SECRET')

def create_token(user: dict) -> str:
    """Create a JWT token for a user."""
    payload = {
        'sub': user['id'],
        'email': user['email'],
        'role': user['role'],
        'iat': datetime.utcnow(),
        'exp': datetime.utcnow() + timedelta(minutes=15)
    }
    return jwt.encode(payload, SECRET, algorithm='HS256')

def verify_token(token: str) -> dict:
    """Verify and decode a JWT token."""
    try:
        payload = jwt.decode(token, SECRET, algorithms=['HS256'])
        return {'valid': True, 'payload': payload}
    except jwt.ExpiredSignatureError:
        return {'valid': False, 'error': 'Token expired'}
    except jwt.InvalidTokenError as e:
        return {'valid': False, 'error': str(e)}

# Flask decorator
from functools import wraps
from flask import request, jsonify

def require_auth(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        auth_header = request.headers.get('Authorization', '')
        if not auth_header.startswith('Bearer '):
            return jsonify({'error': 'No token provided'}), 401
        
        token = auth_header.split(' ')[1]
        result = verify_token(token)
        
        if not result['valid']:
            return jsonify({'error': result['error']}), 401
        
        request.user = result['payload']
        return f(*args, **kwargs)
    return decorated

Java (jjwt)

import io.jsonwebtoken.*;
import io.jsonwebtoken.security.Keys;
import java.security.Key;
import java.util.Date;

public class JwtUtil {
    private static final Key SECRET = Keys.secretKeyFor(SignatureAlgorithm.HS256);
    private static final long EXPIRATION_MS = 15 * 60 * 1000; // 15 minutes
    
    public static String createToken(User user) {
        return Jwts.builder()
            .setSubject(user.getId())
            .claim("email", user.getEmail())
            .claim("role", user.getRole())
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + EXPIRATION_MS))
            .signWith(SECRET)
            .compact();
    }
    
    public static Claims verifyToken(String token) {
        try {
            return Jwts.parserBuilder()
                .setSigningKey(SECRET)
                .build()
                .parseClaimsJws(token)
                .getBody();
        } catch (JwtException e) {
            throw new RuntimeException("Invalid token: " + e.getMessage());
        }
    }
}

7. Security Best Practices

8. Common JWT Vulnerabilities

9. Token Storage: Cookies vs localStorage

Recommended: HttpOnly Cookie with SameSite

// Setting a secure HttpOnly cookie (Node.js/Express)
res.cookie('accessToken', token, {
    httpOnly: true,        // Not accessible via JavaScript
    secure: true,          // HTTPS only
    sameSite: 'strict',    // CSRF protection
    maxAge: 15 * 60 * 1000 // 15 minutes
});

10. Frequently Asked Questions