Skip to main content

Authentication & Authorization Flow 🔐

This document explains the complete authentication and authorization flow used in ShopVerse, from user login to secured service access.

The design focuses on centralized security, stateless authentication, and scalable authorization, following real-world backend practices.

🎯 Design Goals​

  • Authenticate users once
  • Avoid duplicating security logic across services
  • Keep microservices lightweight
  • Ensure secure inter-service trust
  • Support role-based access control (RBAC)

🧠 High-Level Strategy​

ShopVerse uses:

  • JWT-based authentication
  • API Gateway–level validation
  • Header-based identity propagation
  • RBAC enforcement at services

This ensures security without tight coupling.

🔁 Authentication Flow (Step-by-Step)​

1️⃣ User Login​

  • Client sends credentials to Auth Service
  • Auth Service validates credentials
  • JWT token is issued

2️⃣ Token Usage​

  • Client sends JWT in Authorization header
  • All requests go through API Gateway

3️⃣ Gateway Validation​

  • Gateway validates JWT signature & expiration
  • Extracts user identity and role
  • Removes Authorization header
  • Injects trusted headers:
    • X-User-Email
    • X-User-Role

4️⃣ Downstream Authorization​

  • Services trust gateway-injected headers
  • Role-based access control is enforced locally
  • No JWT parsing inside services

🏗️ Authentication Flow Diagram (Mermaid)​

🔐 JWT Token Structure​

The JWT issued by Auth Service contains:

{
  "sub": "user@example.com",
  "role": "CUSTOMER",
  "name": "User Name",
  "iat": 1710000000,
  "exp": 1710003600
}

Key Claims:​

  • sub → User identity (email)
  • role → Authorization role
  • exp → Token expiration

🧩 API Gateway Responsibilities​

The API Gateway is the security backbone.

Responsibilities:​

  • JWT validation
  • Token expiration checks
  • Role extraction
  • Header enrichment
  • Blocking unauthorized requests

Why Validate JWT at Gateway?​

  • Avoid duplicate JWT parsing
  • Faster downstream services
  • Centralized security changes
  • Reduced attack surface

🔁 Header-Based Trust Model​

After validation, the gateway forwards requests with trusted headers:

X-User-Email: user@example.com
X-User-Role: CUSTOMER

Downstream services:

  • Do not accept raw JWT tokens
  • Trust only gateway-provided headers
  • Authenticate requests internally using a custom filter

🛡️ Service-Level Authorization​

Each service enforces RBAC using:

  • OncePerRequestFilter
  • Spring Security SecurityContext
  • Role-based method or endpoint protection

Example:​

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

🧠 Why This Approach Works​

ConcernSolution
Security duplicationCentralized at gateway
Token tamperingJWT signature validation
PerformanceSingle JWT validation
ScalabilityStateless auth
Service simplicityHeader-based auth

⚠️ Failure Scenarios​

❌ Invalid / Expired Token​

  • Gateway blocks request
  • Returns 401 Unauthorized

❌ Missing Headers​

  • Service rejects request
  • Returns 403 Forbidden

❌ Gateway Down​

  • Entire system protected
  • No insecure direct access

📈 Scalability Benefits​

  • Gateway can scale horizontally
  • Services remain stateless
  • No session storage required
  • Easy to integrate new services

🧩 Alternative Approaches (Why Not Used)​

ApproachReason Not Used
Session-based authNot scalable
JWT validation in every serviceDuplication
Shared auth DBTight coupling

📌 Summary​

ShopVerse uses a gateway-centric JWT authentication model that ensures:

  • Centralized security
  • Clean service boundaries
  • High performance
  • Easy scalability
  • Interview-ready explanation

This approach mirrors real-world microservice security designs.