Redirect-Based Microservice SSO Architecture

This repository implements a Modern Redirect-Based Single Sign-On (SSO) Architecture tailored for distributed microservice ecosystems. It demonstrates the exact federated authentication patterns used in production platforms (such as Mandi / Trucking platforms), featuring centralized login UI redirection, secure JWT verification, and loop-free account switching.

---

🏗 Architecture Overview

The system consists of two autonomous Node.js / Express microservices:

1. App 1: Central Identity Provider (IdP) — Port 5001

   • Serves as the central user identity registry (backed by MongoDB & bcrypt).
   • Hosts the unified SSO Login and Registration user interfaces.
   • Handles returnUrl redirections and clearCache=true session purges.
   • Exposes a secure verification endpoint (GET /auth/me) for connected Service Providers.

2. App 2: Service Provider (SP) — Port 5002

   • Represents a connected domain application (e.g., Fleet Dispatches & Logistics).
   • Automatically detects unauthenticated access and initiates OAuth-style redirects to App 1.
   • Extracts signed JWT tokens upon return redirection (/auth-callback?token=...) and validates them directly against App 1's server.
   • Implements robust permission checking with a fallback Switch Account workflow.

---

🔄 The Authentication & SSO Flows

1. Seamless Single Sign-On (SSO)

1. User navigates to App 2 (http://localhost:5002).
2. App 2 detects an unauthenticated session and redirects the user to: http://localhost:5001/login?returnUrl=http://localhost:5002/auth-callback
3. If the user is already authenticated in App 1 (active IdP session), App 1 immediately redirects back with the token.
4. If unauthenticated, the user logs in on App 1. Upon verification, App 1 redirects to: http://localhost:5002/auth-callback?token=<signed_jwt>
5. App 2 verifies the JWT via App 1's backend API (/auth/me), establishes a localized Service Provider session in localStorage, and displays the protected dashboard!

2. Loop-Free Account Switching & Unauthorized Handling

A common pitfall in federated SSO systems is an infinite redirect loop when an authenticated IdP user lacks authorization for a Service Provider app. This project resolves this completely:

• When a user signs in with an unauthorized account (demonstrated by registering an email ending in @guest.com), App 2 intercepts the authentication failure and presents an Access Restricted card.
• Clicking Switch Account redirects the user to App 1 with: http://localhost:5001/login?clearCache=true&returnUrl=http://localhost:5002/auth-callback
• App 1 intercepts clearCache=true, purges all existing local session storage instantly without flashing or spinning, and displays a clean login prompt ready for an authorized account!

---

🚀 Quick Start Guide

1. Open PowerShell in the project root directory (C:\Users\Admin\Desktop\Voyage\SSO).
2. Run the automated start script:

   .\start-all.ps1

3. This script will install dependencies and boot both microservices simultaneously:
   • App 1 (IdP): http://localhost:5001
   • App 2 (SP): http://localhost:5002
4. Open index.html in any web browser to view the interactive Architecture Portal and test the flows!

---

🧪 Testing Scenarios

• Authorized Access: Log in or sign up with any standard email (e.g., user@voyage.com). Navigate between App 1 and App 2 without re-entering credentials.
• Unauthorized Demo (Switch Account): Register a new account ending in @guest.com (e.g., test@guest.com). Try launching App 2 to test the graceful access restriction and seamless session reset!