# ravikisha/node-sso-gateway architecture

> Architecture diagram of the GitHub repository ravikisha/node-sso-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravikisha/node-sso-gateway
- Repository: https://github.com/ravikisha/node-sso-gateway

## Overview

##### Project type and purpose
- This is a full-stack, multi-application Single Sign-On (SSO) system.
- Purpose: Provide a central Node.js/Express SSO Server for user authentication (JWT-based, backed by MongoDB) and multiple consumer applications (client1, client2, etc.) that rely on that server for login/session management.

##### File structure
Top level:
- server/ – the SSO Server
– config/keys – JWT private key
– controller/ – login/register handlers and jwt_helper
– router/ – Express routes (login, register, token-verify)
– views/ – EJS templates for login/register/index
– index.js – main Express app
- client1/, client2/ – identical SSO Consumers
– config/keys – JWT public key
– checkSSORedirect.js – middleware to redirect to SSO Server
– jwt_verify.js – token validation against SSO Server
– isAuthenticated.js – local session guard
– views/ – EJS templates
– index.js – main Express app
Patterns:
– Clear separation of auth service vs. consumers
– Token-based (JWT) stateless interactions
– MVC-like structure in server and clients
– Configuration centralized under config/

##### Key insights from README
- Central SSO Server issues JWTs after credential validation, stores users in MongoDB.
- Consumers redirect to SSO Server for login, then validate the returned token and establish local sessions.
- Supports dynamic registration of consumer domains via allowedOrigins.
- Emphasis on global vs. local sessions, stateless security.

##### Main components & interactions
a. Components:
1. Browser (User Agent)
2. SSO Consumer Apps (client1, client2, …)
3. SSO Authorization Server
4. MongoDB Database
b. Interactions / Data flow:
1. User hits a protected route in Consumer → isAuthenticated middleware
2. If no local session → checkSSORedirect → redirect to SSO Server login page
3. User submits credentials to SSO Server → controller.validate() → on success, JWT issued
4. SSO Server redirects back to Consumer with JWT in query or header
5. Consumer’s jwt_verify.js calls SSO Server /verify endpoint → validation
6. On valid token → establish local session → access protected resource
7. All user data reads/writes on SSO Server go to MongoDB (user collection)
c. Architectural patterns / principles:
– Service segregation: Auth service vs. clients
– Stateless tokens for cross-domain auth
– Middleware pipelines for authentication/authorization
– Config-driven allowedOrigins for dynamic consumer onboarding
d. Key technologies:
– Node.js, Express.js (server framework)
– JSON Web Tokens (JWT) for stateless auth
– MongoDB (user store)
– EJS templates for server-side views
– bcrypt for password hashing (in controllers)

##### Detailed elements to capture
– SSO Server’s internal chain: Express app → router/index.js → controller/jwt_helper → MongoDB
– Consumers’ chain: Express app → checkSSORedirect → jwt_verify → isAuthenticated → views
– Global vs. local session distinction (annotate two session stores or notes)
– allowedOrigins config lookup on the SSO Server before token issuance
– Logout flow: Consumer session clear → call SSO Server logout endpoint → destroy global session

## Diagram (Mermaid)

```mermaid
graph TB
    %% Actors
    Browser(("Browser")):::frontend

    %% Consumer Layer
    subgraph "Consumer Tier"
        direction TB
        subgraph "client1"
            C1App["Express App"] 
            C1Check["checkSSORedirect()"]
            C1Verify["jwt_verify()"]
            C1Auth["isAuthenticated()"]
            C1Views["EJS Views"]
        end
        subgraph "client2"
            C2App["Express App"]
            C2Check["checkSSORedirect()"]
            C2Verify["jwt_verify()"]
            C2Auth["isAuthenticated()"]
            C2Views["EJS Views"]
        end
    end

    %% Auth Server Layer
    subgraph "SSO Authorization Server"
        direction TB
        ServerApp["Express App"]
        Router["Router (routes)"]
        Controller["Controller (login/register)"]
        JWTHelper["jwt_helper()"]
        Config["Config (allowedOrigins, DB URI)"]
        ViewsAuth["EJS Views"]
        DB[(MongoDB)] 
    end

    %% Flows Consumer1
    Browser -->|"Access protected route"| C1Auth
    C1Auth -->|"No session"| C1Check
    C1Check -->|"Redirect to login"| ServerApp

    %% Auth login flow
    ServerApp -->|"route/login"| Router
    Router -->|"validate()"| Controller
    Controller -->|"hash/compare"| JWTHelper
    JWTHelper -->|"user data"| Config
    Config --> DB
    Controller -->|"Issue JWT"| ServerApp
    ServerApp -->|"Redirect with JWT"| Browser

    %% Verify flow Consumer1
    Browser -->|"JWT token"| C1Verify
    C1Verify -->|"call /verify"| ServerApp
    ServerApp -->|"route/verify"| Router
    Router -->|"verifyToken()"| JWTHelper
    JWTHelper -->|"allowedOrigins lookup"| Config
    Config --> DB
    C1Verify -->|"Valid→session"| C1Auth
    C1Auth -->|"Access resource"| C1Views

    %% Logout flow Consumer1
    C1Auth -->|"logout"| ServerApp
    ServerApp -->|"destroy session"| Controller

    %% Consumer2 same flows (dotted)
    Browser -.-> C2Auth
    C2Auth -.-> C2Check
    C2Check -.-> ServerApp

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000
    classDef service fill:#90EE90,stroke:#000,color:#000
    classDef db fill:#FFA500,stroke:#000,color:#000

    class Browser,ViewsAuth,C1Views,C2Views frontend
    class ServerApp,Router,Controller,JWTHelper,Config,C1App,C1Check,C1Verify,C1Auth,C2App,C2Check,C2Verify,C2Auth service
    class DB db

    %% Click Events - SSO Server
    click ServerApp "https://github.com/ravikisha/node-sso-gateway/blob/main/server/index.js"
    click Config "https://github.com/ravikisha/node-sso-gateway/blob/main/server/config/index.js"
    click Config "https://github.com/ravikisha/node-sso-gateway/blob/main/server/config/keys/jwtPrivate.key"
    click Router "https://github.com/ravikisha/node-sso-gateway/blob/main/server/router/index.js"
    click Controller "https://github.com/ravikisha/node-sso-gateway/blob/main/server/controller/index.js"
    click JWTHelper "https://github.com/ravikisha/node-sso-gateway/blob/main/server/controller/jwt_helper.js"
    click ViewsAuth "https://github.com/ravikisha/node-sso-gateway/tree/main/server/views"
    %% Click Events - client1
    click C1App "https://github.com/ravikisha/node-sso-gateway/blob/main/client1/index.js"
    click C1Check "https://github.com/ravikisha/node-sso-gateway/blob/main/client1/checkSSORedirect.js"
    click C1Verify "https://github.com/ravikisha/node-sso-gateway/blob/main/client1/jwt_verify.js"
    click C1Auth "https://github.com/ravikisha/node-sso-gateway/blob/main/client1/isAuthenticated.js"
    click C1Config "https://github.com/ravikisha/node-sso-gateway/blob/main/client1/config/index.js"
    click C1Config "https://github.com/ravikisha/node-sso-gateway/blob/main/client1/config/keys/jwtPublic.key"
    click C1Views "https://github.com/ravikisha/node-sso-gateway/tree/main/client1/views"
    %% Click Events - client2
    click C2App "https://github.com/ravikisha/node-sso-gateway/blob/main/client2/index.js"
    click C2Check "https://github.com/ravikisha/node-sso-gateway/blob/main/client2/checkSSORedirect.js"
    click C2Verify "https://github.com/ravikisha/node-sso-gateway/blob/main/client2/jwt_verify.js"
    click C2Auth "https://github.com/ravikisha/node-sso-gateway/blob/main/client2/isAuthenticated.js"
    click C2Config "https://github.com/ravikisha/node-sso-gateway/blob/main/client2/config/index.js"
    click C2Config "https://github.com/ravikisha/node-sso-gateway/blob/main/client2/config/keys/jwtPublic.key"
    click C2Views "https://github.com/ravikisha/node-sso-gateway/tree/main/client2/views"
```
