What is a JSON Web Token?

A JSON Web Token (JWT) is a compact, URL‑safe means of representing claims between two parties. It is digitally signed, allowing the receiver to verify its integrity without contacting the issuer. In modern APIs, JWTs replace traditional session identifiers, enabling stateless authentication across distributed services.

Structure of a Token

A JWT consists of three Base64URL‑encoded parts separated by dots:

1. Header - Indicates the signing algorithm (e.g., HS256 or RS256).
2. Payload - Contains registered claims (iss, sub, exp, etc.) and custom application data.
3. Signature - The result of signing the concatenated header and payload with the server’s secret key or private key.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNjMwMDAwMDAwfQ. SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Common Pitfalls and How to Avoid Them

Pitfall	Impact	Mitigation
Storing secrets in code	Credential leakage	Use environment variables or secret managers
Long‑lived tokens	Increased attack window	Set reasonable exp and implement refresh tokens
No token revocation	Compromised tokens stay valid	Maintain a revocation list or use short‑lived access tokens
Using weak algorithms	Signature forgery	Prefer RS256 or ES256 over HS256 for asymmetric verification

Minimal Token Generation Example (Node.js)

const jwt = require('jsonwebtoken');
const privateKey = require('fs').readFileSync('./keys/private.pem');

function generateAccessToken(userId) { const payload = { sub: userId, iss: 'auth.myapp.com' }; const options = { algorithm: 'RS256', expiresIn: '15m' }; return jwt.sign(payload, privateKey, options); }

console.log(generateAccessToken('12345'));

This snippet demonstrates how to produce a signed token using RSA keys, a best practice for production environments.

Stateless vs. Stateful Authentication

Stateless JWT verification eliminates the need for a central session store, enabling horizontal scaling. However, pure statelessness makes revocation difficult. A hybrid approach-stateless access tokens paired with stateful refresh tokens-provides both scalability and control.

Key Management Strategy

Secure key rotation is vital. Store private keys in a dedicated secret manager (AWS KMS, HashiCorp Vault, or Azure Key Vault). Public keys should be exposed via a JWKS endpoint so services can fetch them dynamically, supporting key rotation without downtime.

+-------------------+ +-------------------+ | Auth Service | <---> | Secret Manager | +-------------------+ +-------------------+ | v JWKS Endpoint (/.well-known/jwks.json)

Token Revocation Techniques

1. Allow‑list Refresh Tokens - Store refresh token identifiers in a fast datastore (Redis). When a refresh is requested, validate the identifier; removal instantly revokes future token issuance.
2. Block‑list Access Tokens - Keep a short‑lived block‑list for compromised access tokens. Because access tokens expire quickly (5‑15 minutes), the list remains small and can be cached.
3. Versioned Claims - Include a token_version claim. Increment the version in the user record upon password change or logout, rendering older tokens invalid.

Microservices Integration Pattern

Each microservice validates JWTs independently using the JWKS endpoint. The flow looks like:

1. Client logs in via the Auth Service and receives an access token & refresh token.
2. Client calls api.serviceA.com with the access token in the Authorization: Bearer <token> header.
3. Service A fetches the public key from the JWKS endpoint (cached) and verifies the token.
4. Service A extracts the user ID and role claims to enforce ACLs.
5. When the token nears expiration, the client uses the refresh token endpoint to obtain a new access token.

High‑Availability Considerations

• Deploy the Auth Service behind a load balancer with at least two instances.
• Use a distributed cache (Redis Cluster) for refresh token allow‑listing.
• Enable rate limiting on token issuance endpoints to mitigate brute‑force attacks.
• Log all token generation and revocation events for audit trails.

By separating concerns-key management, token issuance, verification, and revocation-you create a modular, maintainable system that can evolve without service interruptions.

Project Setup

bash mkdir jwt-auth-system && cd jwt-auth-system npm init -y npm install express jsonwebtoken dotenv ioredis joi helmet cors npm install --save-dev nodemon

Create a .env file to store secret paths and configuration:

PORT=3000 ACCESS_TOKEN_EXP=15m REFRESH_TOKEN_EXP=7d PRIVATE_KEY_PATH=./keys/private.pem PUBLIC_KEY_PATH=./keys/public.pem REDIS_URL=redis://localhost:6379

Middleware Design

The authentication middleware extracts the token, verifies it against the JWKS‑cached public key, and attaches the decoded payload to req.user.

// middleware/auth.js
const jwt = require('jsonwebtoken');
const fs = require('fs');
const publicKey = fs.readFileSync(process.env.PUBLIC_KEY_PATH);

module.exports = (req, res, next) => { const authHeader = req.headers['authorization']; const token = authHeader && authHeader.split(' ')[1]; if (!token) return res.sendStatus(401);

jwt.verify(token, publicKey, { algorithms: ['RS256'] }, (err, payload) => { if (err) return res.sendStatus(403); req.user = payload; next(); }); };

Refresh Token Flow

Refresh tokens are stored in Redis with a UUID as the key. When a client presents a refresh token, the service validates its existence and issues a new pair of tokens.

// routes/auth.js
const express = require('express');
const jwt = require('jsonwebtoken');
const { v4: uuidv4 } = require('uuid');
const Redis = require('ioredis');
const router = express.Router();
const redis = new Redis(process.env.REDIS_URL);
const privateKey = fs.readFileSync(process.env.PRIVATE_KEY_PATH);

function signAccess(userId) { return jwt.sign({ sub: userId }, privateKey, { algorithm: 'RS256', expiresIn: process.env.ACCESS_TOKEN_EXP, issuer: 'auth.myapp.com' }); }

router.post('/login', async (req, res) => { const { username, password } = req.body; // Assume validation elsewhere const userId = await authenticateUser(username, password); if (!userId) return res.status(401).json({ error: 'Invalid credentials' });

const accessToken = signAccess(userId); const refreshId = uuidv4(); await redis.set(refresh:${refreshId}, userId, 'EX', 60 * 60 * 24 * 7); // 7 days const refreshToken = jwt.sign({ jti: refreshId }, privateKey, { algorithm: 'RS256', expiresIn: process.env.REFRESH_TOKEN_EXP, issuer: 'auth.myapp.com' });

res.json({ accessToken, refreshToken }); });

router.post('/refresh', async (req, res) => { const { refreshToken } = req.body; if (!refreshToken) return res.sendStatus(400);

jwt.verify(refreshToken, privateKey, { algorithms: ['RS256'] }, async (err, payload) => { if (err) return res.sendStatus(403); const storedUserId = await redis.get(refresh:${payload.jti}); if (!storedUserId) return res.sendStatus(403);

// Rotate refresh token
await redis.del(`refresh:${payload.jti}`);
const newRefreshId = uuidv4();
await redis.set(`refresh:${newRefreshId}`, storedUserId, 'EX', 60 * 60 * 24 * 7);
const newRefreshToken = jwt.sign({ jti: newRefreshId }, privateKey, {
  algorithm: 'RS256',
  expiresIn: process.env.REFRESH_TOKEN_EXP,
  issuer: 'auth.myapp.com'
});

const newAccessToken = signAccess(storedUserId);
res.json({ accessToken: newAccessToken, refreshToken: newRefreshToken });

}); });

module.exports = router;

Error Handling and Security Headers

Add helmet and cors globally, and define a centralized error handler to avoid leaking stack traces.

// app.js
require('dotenv').config();
const express = require('express');
const helmet = require('helmet');
const cors = require('cors');
const authRoutes = require('./routes/auth');
const authMiddleware = require('./middleware/auth');

const app = express(); app.use(helmet()); app.use(cors()); app.use(express.json());

app.use('/auth', authRoutes);

app.get('/protected', authMiddleware, (req, res) => { res.json({ message: Hello ${req.user.sub}, you have accessed a protected route. }); });

// Global error handler app.use((err, req, res, next) => { console.error(err); res.status(500).json({ error: 'Internal Server Error' }); });

app.listen(process.env.PORT, () => console.log(Server running on port ${process.env.PORT}));

The code above showcases a full production‑grade flow: secure key usage, refresh‑token rotation, Redis‑backed allow‑list, and stateless access‑token validation.

Deploying the Service

• Dockerfile - Build a minimal Node image, copy keys from a secret volume.
• Kubernetes - Deploy as a Deployment with readinessProbe hitting /health. Use a ConfigMap for JWKS exposure and Secrets for private keys.
• CI/CD - Run unit tests (jest) and static analysis (eslint) before pushing the Docker image.

Following these steps yields a resilient JWT authentication service ready for production traffic.

Q1: How frequently should I rotate JWT signing keys? A: Rotate asymmetric keys at least every 30 days in high‑risk environments. Publish the new public key via the JWKS endpoint while retaining the previous key for a grace period equal to the longest token lifetime. This approach guarantees seamless verification during key rollover.

Q2: Can I store user roles inside the JWT payload? A: Yes, embedding role or permission claims (roles, scopes) is common and enables authorization decisions without additional DB calls. However, keep the token size modest and avoid sensitive data, because JWTs are base64‑encoded and can be decoded by anyone possessing the token.

Q3: What is the difference between a block‑list and an allow‑list for token revocation? A: An allow‑list (commonly used for refresh tokens) stores identifiers of tokens that are permitted to be exchanged for new access tokens. A block‑list records identifiers of tokens that have been explicitly revoked before their natural expiration, typically for short‑lived access tokens. Allow‑lists are ideal when you need to maintain a list of active sessions; block‑lists are useful for emergency revocation of compromised tokens.

Q4: Should I use symmetric (HS256) or asymmetric (RS256) algorithms in production? A: Asymmetric algorithms are recommended for distributed systems because the private key remains on the issuer, while public keys can be safely distributed to all verifying services. This reduces the risk of key exposure and simplifies key rotation through JWKS.

Q5: How can I protect against replay attacks with JWTs? A: Include a unique identifier (jti) claim and store its usage in a short‑term cache. Reject any token whose jti appears more than once within its validity window. Combine this with TLS everywhere to prevent token interception.

Designing a production‑ready JWT authentication system requires a blend of cryptographic rigor, scalable architecture, and disciplined operational practices. By leveraging asymmetric keys, a JWKS endpoint, and short‑lived access tokens paired with stateful refresh tokens, you achieve both stateless performance and precise revocation control. Implementing the workflow in Node.js-complete with secure middleware, Redis‑backed token allow‑listing, and robust error handling-demonstrates how these concepts translate into actionable code.

Key takeaways:

• Store private keys in a secret manager and expose public keys via JWKS for seamless key rotation.
• Use refresh‑token rotation and versioned claims to invalidate compromised sessions promptly.
• Adopt a hybrid revocation strategy-allow‑list for refresh tokens and block‑list for rare access‑token invalidation.
• Harden the service with security headers, rate limiting, and centralized logging for auditability.

When these patterns are applied consistently across microservices, the authentication layer becomes a reliable foundation that scales with traffic while protecting user identities.

By following the guidelines and code examples provided, you can confidently launch an authentication service that meets enterprise security standards and delivers a smooth developer experience.