Skip to main content

JWT Security Model 🔐

This document explains how JSON Web Tokens (JWT) are used in ShopVerse to provide secure, stateless authentication and authorization across microservices.

JWT is a core security mechanism in ShopVerse and forms the foundation of the API Gateway–based security design.

🎯 Why JWT in ShopVerse?​

JWT was chosen because it provides:

  • Stateless authentication
  • High performance (no session lookup)
  • Easy horizontal scaling
  • Secure identity propagation across services
  • Industry-standard security model

JWT fits naturally with microservices architecture.

🧠 High-Level JWT Strategy​

ShopVerse uses JWT with the following principles:

  • JWT is issued only by Auth Service
  • JWT is validated only at API Gateway
  • Downstream services never parse JWT
  • Services trust gateway-injected headers

This avoids duplication and security inconsistencies.

🔑 JWT Lifecycle​

🧾 JWT Token Structure​

JWT consists of three parts:

HEADER.PAYLOAD.SIGNATURE

📄 JWT Header​

{
  "alg": "HS512",
  "typ": "JWT"
}
  • HS512 → HMAC with SHA-512
  • Ensures strong cryptographic signing

📦 JWT Payload (Claims)​

{
  "sub": "user@example.com",
  "role": "CUSTOMER",
  "name": "John Doe",
  "iat": 1710000000,
  "exp": 1710003600
}
ClaimPurpose
subUser identity (email)
roleAuthorization role
iatIssued at
expExpiration time

🔐 JWT Signature​

  • Created using server-side secret key
  • Prevents token tampering
  • Validated at API Gateway

⏱ Token Expiration Strategy​

  • Tokens have short expiration
  • Reduces risk if token is compromised
  • Forces periodic re-authentication

Example:

Expiration: 1 hour

🛡️ API Gateway JWT Validation​

The API Gateway performs:

  • Signature validation
  • Token expiration check
  • Claim extraction
  • Role extraction
  • Request rejection on failure

If JWT is invalid:​

401 Unauthorized

🔁 Header-Based Identity Propagation​

After successful validation, the gateway:

  • Removes Authorization header
  • Injects trusted headers:
X-User-Email: user@example.com
X-User-Role: CUSTOMER

Downstream services trust only these headers.

🔐 Service-Level Authorization​

Each service:

  • Uses a custom security filter
  • Builds SecurityContext
  • Enforces RBAC

Example:

  • ADMIN → Create / Update / Delete
  • CUSTOMER → Read / Order / Pay

⚠️ Security Threat Mitigations​

ThreatMitigation
Token tamperingSignature validation
Replay attackToken expiration
Credential theftBCrypt hashing
Service bypassGateway-only access
JWT leakageHeader removal

❌ Why JWT Is NOT Parsed in Services​

Parsing JWT in every service causes:

  • Code duplication
  • Security drift
  • Performance overhead

Centralizing JWT validation:

  • Improves security
  • Simplifies services
  • Makes auth changes easier

🔄 Failure Scenarios​

❌ Expired Token​

  • Gateway rejects request
  • Client must re-login

❌ Invalid Signature​

  • Request blocked immediately

❌ Missing Headers​

  • Service returns 403 Forbidden

📈 Scalability Benefits​

  • No session storage
  • Stateless services
  • Easy horizontal scaling
  • Load-balancer friendly

📌 Best Practices Followed​

  • Strong signing algorithm (HS512)
  • Short-lived tokens
  • Centralized validation
  • No sensitive data in payload
  • Secure secret management

🧠 Interview Explanation (One-Liner)​

“We use JWT for stateless authentication, validate it centrally at the API Gateway, and propagate trusted identity headers to downstream services for RBAC.”

📌 Summary​

The JWT security model in ShopVerse provides:

  • Strong authentication
  • Clean authorization
  • Centralized security control
  • Microservices-friendly scalability

JWT acts as the security backbone of the entire system.