# SSO Implementation for RE Workflow Management System

## 1. Landing Page

The RE Workflow Management System serves as a unified landing page and application portal for workflow request management. Users access the application through a web-based interface that provides:

- **Unified Login Experience**: Single sign-on (SSO) integration with Okta Identity Provider
- **Application Dashboard**: Centralized view of workflow requests, approvals, and activities
- **Role-Based Access**: Personalized interface based on user roles (USER, MANAGEMENT, ADMIN)
- **Request Management**: Create, view, and manage workflow requests with multi-level approvals

### Landing Page Features

- **Dashboard**: Overview of open requests, pending approvals, and system metrics
- **Request Creation**: Guided wizards for creating custom requests and claim management workflows
- **Request Tracking**: Real-time status updates and activity tracking
- **Document Management**: Upload, preview, and download documents with GCS integration
- **Work Notes**: Collaborative communication within request context
- **Notifications**: Real-time alerts for approvals, assignments, and system events

---

## 2. System Architecture

### 2a. Architecture for Frontend (RE Workflow Application)

**Technology Stack:**
- **Framework**: React 18 with TypeScript
- **Build Tool**: Vite
- **Routing**: React Router v6
- **State Management**: Redux Toolkit (authSlice, storeSlice) + React Context (AuthContext)
- **UI Components**: shadcn/ui, Radix UI, Tailwind CSS
- **HTTP Client**: Axios with interceptors
- **Authentication**: Okta Sign-In Widget (production) / Token Exchange (development)

**Frontend Architecture Components:**

```
┌─────────────────────────────────────────────────────────────┐
│                    User's Web Browser                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  React Application (Vite + React Router)               │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │  │
│  │  │ AuthContext  │  │ Redux Store  │  │ Components  │ │  │
│  │  │ (SSO Flow)   │  │ (State Mgmt) │  │ (UI Layer)  │ │  │
│  │  └──────────────┘  └──────────────┘  └─────────────┘ │  │
│  │         │                  │                  │        │  │
│  │         └──────────────────┼──────────────────┘        │  │
│  │                            │                           │  │
│  │                    ┌───────▼────────┐                  │  │
│  │                    │  Axios Client  │                  │  │
│  │                    │  (withCredentials)                │  │
│  │                    └───────┬────────┘                  │  │
│  └────────────────────────────┼──────────────────────────┘  │
└────────────────────────────────┼──────────────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   Backend API Server    │
                    │   (Express + Node.js)   │
                    └────────────────────────┘
```

**Mermaid Diagram - Frontend Architecture:**

```mermaid
graph TB
    Browser[User's Web Browser]
    ReactApp[React Application<br/>Vite + React Router]
    AuthContext[AuthContext<br/>SSO Flow]
    ReduxStore[Redux Store<br/>State Management]
    Components[Components<br/>UI Layer]
    AxiosClient[Axios Client<br/>withCredentials]
    BackendAPI[Backend API Server<br/>Express + Node.js]
    
    Browser --> ReactApp
    ReactApp --> AuthContext
    ReactApp --> ReduxStore
    ReactApp --> Components
    AuthContext --> AxiosClient
    ReduxStore --> AxiosClient
    Components --> AxiosClient
    AxiosClient --> BackendAPI
```

**Key Frontend Files:**
- `src/contexts/AuthContext.tsx`: Authentication state management and SSO flow
- `src/services/authApi.ts`: API client with token refresh interceptors
- `src/utils/tokenManager.ts`: Token storage and management (localStorage in dev, httpOnly cookies in prod)
- `src/pages/Auth/AuthCallback.tsx`: Handles OAuth callback from Okta
- `src/App.tsx`: Main routing and application structure

**Authentication Flow (Frontend):**

1. **Production Mode (SSO via Okta)**:
   - User navigates to application
   - Okta Sign-In Widget initiates authentication
   - User authenticates with Okta (MFA if enabled)
   - Okta redirects to `/login/callback` with authorization code
   - Frontend exchanges code for tokens via `/api/v1/auth/token-exchange`
   - Backend sets httpOnly cookies (`accessToken`, `refreshToken`)
   - User is redirected to dashboard

2. **Development Mode (Localhost)**:
   - User navigates to application
   - Okta Sign-In Widget initiates authentication
   - After Okta authentication, frontend receives authorization code
   - Frontend calls `/api/v1/auth/token-exchange` with code
   - Backend returns tokens in response body (for cross-port development)
   - Tokens stored in localStorage for development convenience
   - User is redirected to dashboard

**Session Management:**
- **Production**: Tokens stored in httpOnly cookies (secure, not accessible via JavaScript)
- **Development**: Tokens stored in localStorage (for debugging and cross-port setup)
- **Token Refresh**: Automatic refresh via Axios interceptor when access token expires
- **Logout**: Clears cookies and redirects to Okta logout endpoint

### 2b. Architecture for Backend (API Server)

**Technology Stack:**
- **Runtime**: Node.js 22 LTS
- **Language**: TypeScript 5.7
- **Framework**: Express.js 4.21
- **Database**: PostgreSQL 16
- **ORM**: Sequelize 6.37
- **Authentication**: JWT (JSON Web Tokens)
- **Session**: HttpOnly cookies (production) / JWT tokens (development)

**Backend Architecture Components:**

```
┌─────────────────────────────────────────────────────────────┐
│              Express.js Application Server                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Middleware Layer                                      │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │   CORS   │ │  Helmet  │ │  Cookie  │ │  Auth    │ │  │
│  │  │          │ │ (Security)│ │  Parser │ │Middleware│ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Route Handlers                                        │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │   Auth   │ │ Workflow │ │ Document │ │  User    │ │  │
│  │  │Controller│ │Controller│ │Controller│ │Controller│ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Service Layer                                        │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │   Auth   │ │ Workflow │ │ Document │ │  User    │ │  │
│  │  │ Service │ │ Service  │ │ Service  │ │ Service  │ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Data Access Layer                                    │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │   User   │ │Workflow  │ │ Document │ │ Activity │ │  │
│  │  │  Model   │ │  Model   │ │  Model   │ │  Model   │ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  PostgreSQL  │    │  Okta API    │    │  GCS Bucket   │
│   Database   │    │  (IdP)       │    │  (Storage)   │
└──────────────┘    └──────────────┘    └──────────────┘
```

**Mermaid Diagram - Backend Architecture:**

```mermaid
graph TB
    ExpressApp[Express.js Application Server]
    
    subgraph Middleware["Middleware Layer"]
        CORS[CORS]
        Helmet[Helmet Security]
        CookieParser[Cookie Parser]
        AuthMiddleware[Auth Middleware]
    end
    
    subgraph Controllers["Route Handlers"]
        AuthController[Auth Controller]
        WorkflowController[Workflow Controller]
        DocumentController[Document Controller]
        UserController[User Controller]
    end
    
    subgraph Services["Service Layer"]
        AuthService[Auth Service]
        WorkflowService[Workflow Service]
        DocumentService[Document Service]
        UserService[User Service]
    end
    
    subgraph Models["Data Access Layer"]
        UserModel[User Model]
        WorkflowModel[Workflow Model]
        DocumentModel[Document Model]
        ActivityModel[Activity Model]
    end
    
    PostgreSQL[(PostgreSQL Database)]
    OktaAPI[Okta API IdP]
    GCS[GCS Bucket Storage]
    
    ExpressApp --> Middleware
    Middleware --> Controllers
    Controllers --> Services
    Services --> Models
    Models --> PostgreSQL
    AuthService --> OktaAPI
    DocumentService --> GCS
```

**Key Backend Files:**
- `src/app.ts`: Express application setup, middleware configuration
- `src/routes/auth.routes.ts`: Authentication endpoints
- `src/controllers/auth.controller.ts`: Authentication request handlers
- `src/services/auth.service.ts`: Authentication business logic
- `src/middlewares/auth.middleware.ts`: JWT token validation middleware
- `src/config/sso.ts`: SSO configuration (Okta, JWT secrets)

**Authentication Endpoints:**

1. **POST `/api/v1/auth/token-exchange`** (No auth required)
   - Exchanges Okta authorization code for JWT tokens
   - Creates/updates user in database
   - Sets httpOnly cookies (production) or returns tokens (development)

2. **POST `/api/v1/auth/sso-callback`** (No auth required)
   - Legacy endpoint for direct SSO callback
   - Accepts SSO user data, creates/updates user
   - Returns JWT tokens

3. **POST `/api/v1/auth/login`** (No auth required)
   - Username/password authentication via Okta Resource Owner Password flow
   - For API clients (Postman, mobile apps)
   - Returns JWT tokens

4. **POST `/api/v1/auth/refresh`** (No auth required)
   - Refreshes access token using refresh token
   - Accepts refresh token from request body or httpOnly cookie
   - Returns new access token

5. **GET `/api/v1/auth/me`** (Auth required)
   - Returns current authenticated user profile

6. **POST `/api/v1/auth/logout`** (Optional auth)
   - Clears authentication cookies
   - Logs user activity

**Cookie Configuration:**
- **Name**: `accessToken`, `refreshToken`
- **HttpOnly**: `true` (prevents JavaScript access)
- **Secure**: `true` in production (HTTPS only)
- **SameSite**: `lax` (development) / `none` (production for cross-domain)
- **MaxAge**: 24 hours (accessToken), 7 days (refreshToken)
- **Path**: `/`

---

## 3. Deployment Architecture

### Deployment Environment

**Current Deployment:**
- **Environment**: Development/Staging
- **Region**: To be configured based on organizational requirements

### User Domain

- **Domain**: To be configured (e.g., `rebridge.co.in` or organization-specific domain)
- **Purpose**: Unified domain for SSO and application access
- **Integration**: Federated with Okta Identity Provider

### Deployment Components

**Frontend Deployment:**
- **Build**: Vite production build (`npm run build`)
- **Static Hosting**: Served via Express static middleware or CDN
- **Environment Variables**: 
  - `VITE_API_BASE_URL`: Backend API URL
  - `VITE_OKTA_DOMAIN`: Okta domain for authentication
  - `VITE_OKTA_CLIENT_ID`: Okta client ID

**Backend Deployment:**
- **Runtime**: Node.js 22 LTS
- **Process Manager**: PM2 (recommended for production)
- **Reverse Proxy**: Nginx (recommended for SSL termination and load balancing)
- **Database**: PostgreSQL 16 (managed service or self-hosted)
- **File Storage**: Google Cloud Storage (GCS) for document storage
- **Environment Variables**: See `.env.example` for complete list

**Key Environment Variables:**
```env
# Server Configuration
NODE_ENV=production
PORT=5000
FRONTEND_URL=https://rebridge.co.in

# Database
DB_HOST=postgresql-host
DB_PORT=5432
DB_NAME=re_workflow_db
DB_USER=postgres
DB_PASSWORD=secure_password

# JWT Configuration
JWT_SECRET=your-secret-key
JWT_EXPIRY=24h
REFRESH_TOKEN_EXPIRY=7d

# Okta Configuration
OKTA_DOMAIN=https://dev-830839.oktapreview.com
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret

# GCS Configuration
GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_BUCKET_NAME=re-workflow-documents
GCP_KEY_FILE=./config/gcp-key.json
GCP_BUCKET_REGION=asia-south1
GCP_BUCKET_PUBLIC=true
```

---

## 4. Identity Provider (IdP) - Okta

### IdP Configuration

**Identity Provider**: Okta
- **Domain**: Configurable via `OKTA_DOMAIN` environment variable
- **Default**: `https://dev-830839.oktapreview.com`
- **Protocol**: OAuth 2.0 / OpenID Connect (OIDC)
- **Grant Types**: Authorization Code, Resource Owner Password Credentials

### IdP Features

**Authentication:**
- Username/password authentication
- Multi-Factor Authentication (MFA) support
- Conditional Access Policies
- Session management

**User Management:**
- User directory management
- Group/role mappings
- User provisioning and deprovisioning
- Profile synchronization

**Integration:**
- OAuth 2.0 Authorization Code flow (web applications)
- Resource Owner Password Credentials flow (API clients)
- Token exchange and validation
- User info endpoint integration

### IdP Integration Flow

1. **User Authentication**:
   - User initiates login from frontend
   - Frontend redirects to Okta Sign-In Widget
   - User enters credentials (and MFA if enabled)
   - Okta validates credentials and issues authorization code

2. **Token Exchange**:
   - Frontend receives authorization code
   - Frontend calls backend `/api/v1/auth/token-exchange` with code
   - Backend exchanges code for access token with Okta
   - Backend fetches user info from Okta userinfo endpoint
   - Backend creates/updates user in local database
   - Backend generates JWT tokens (access + refresh)
   - Backend sets httpOnly cookies (production) or returns tokens (development)

3. **Token Validation**:
   - Backend validates JWT tokens on each API request
   - Middleware (`authenticateToken`) verifies token signature and expiry
   - User record is fetched from database to ensure active status
   - User info is attached to request object for authorization

---

## 5. User Authentication Flow for RE Workflow System

### 5.1 Web Application Flow (Production)

**Sequence:**
1. User navigates to RE Workflow application (e.g., `https://rebridge.co.in`)
2. **Authentication**: Frontend checks for existing session (httpOnly cookie)
   - If no valid session, redirects to Okta Sign-In Widget
   - User enters credentials (and MFA if enabled) on Okta login page
3. **Token Issuance**: Upon successful authentication, Okta issues authorization code
4. **Token Exchange**: Frontend exchanges authorization code for tokens via backend
5. **User Creation/Update**: Backend creates or updates user in local database based on Okta user info
6. **JWT Generation**: Backend generates JWT access and refresh tokens
7. **Cookie Setting**: Backend sets httpOnly cookies (`accessToken`, `refreshToken`)
8. **Token Validation**: On subsequent requests, backend validates JWT token from cookie
9. **Access Control**: Backend applies role-based access controls (USER, MANAGEMENT, ADMIN)

**Mermaid Sequence Diagram - Web Application Authentication Flow:**

```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant ReactApp as React Application
    participant Okta as Okta IdP
    participant Backend as Backend API
    participant DB as PostgreSQL
    
    User->>Browser: Navigate to application
    Browser->>ReactApp: Load application
    ReactApp->>ReactApp: Check for httpOnly cookie
    alt No valid session
        ReactApp->>Okta: Redirect to Sign-In Widget
        User->>Okta: Enter credentials + MFA
        Okta->>Okta: Validate credentials
        Okta->>ReactApp: Redirect with authorization code
        ReactApp->>Backend: POST /api/v1/auth/token-exchange (code)
        Backend->>Okta: Exchange code for tokens
        Okta->>Backend: Return access token + user info
        Backend->>DB: Create/Update user
        DB->>Backend: User record
        Backend->>Backend: Generate JWT tokens
        Backend->>ReactApp: Set httpOnly cookies (accessToken, refreshToken)
        ReactApp->>Browser: Redirect to dashboard
    else Valid session exists
        ReactApp->>Browser: Show dashboard
    end
    
    User->>ReactApp: Make API request
    ReactApp->>Backend: API request (with cookie)
    Backend->>Backend: Validate JWT token
    Backend->>DB: Fetch user (verify active)
    DB->>Backend: User data
    Backend->>Backend: Apply RBAC
    Backend->>ReactApp: Return data
    ReactApp->>User: Display data
```

### 5.2 API Client Flow (Development/Postman)

**Sequence:**
1. Client calls `POST /api/v1/auth/login` with username and password
2. **Okta Authentication**: Backend authenticates with Okta using Resource Owner Password flow
3. **Token Retrieval**: Backend receives access token and user info from Okta
4. **User Creation/Update**: Backend creates or updates user in local database
5. **JWT Generation**: Backend generates JWT access and refresh tokens
6. **Token Return**: Backend returns tokens in response body (for API clients)

### 5.3 Token Refresh Flow

**Sequence:**
1. Client makes API request with access token
2. **Token Expiry**: If access token is expired, backend returns 401 Unauthorized
3. **Automatic Refresh**: Frontend Axios interceptor catches 401 and calls `/api/v1/auth/refresh`
4. **Refresh Token Validation**: Backend validates refresh token (from cookie or request body)
5. **New Token Generation**: Backend generates new access token
6. **Cookie Update**: Backend sets new access token in httpOnly cookie (production)
7. **Request Retry**: Frontend retries original request with new token

**Mermaid Sequence Diagram - Token Refresh Flow:**

```mermaid
sequenceDiagram
    participant User
    participant ReactApp as React Application
    participant AxiosInterceptor as Axios Interceptor
    participant Backend as Backend API
    participant DB as PostgreSQL
    
    User->>ReactApp: Trigger API request
    ReactApp->>Backend: API request (with accessToken cookie)
    Backend->>Backend: Validate JWT token
    alt Token expired
        Backend->>ReactApp: 401 Unauthorized
        ReactApp->>AxiosInterceptor: Catch 401 error
        AxiosInterceptor->>Backend: POST /api/v1/auth/refresh (refreshToken)
        Backend->>Backend: Validate refresh token
        Backend->>DB: Fetch user (verify active)
        DB->>Backend: User data
        Backend->>Backend: Generate new access token
        Backend->>ReactApp: Set new accessToken cookie
        AxiosInterceptor->>Backend: Retry original request (with new token)
        Backend->>Backend: Validate new JWT token
        Backend->>DB: Fetch data
        DB->>Backend: Return data
        Backend->>ReactApp: 200 OK (data)
        ReactApp->>User: Display data
    else Token valid
        Backend->>DB: Fetch data
        DB->>Backend: Return data
        Backend->>ReactApp: 200 OK (data)
        ReactApp->>User: Display data
    end
```

### 5.4 Logout Flow

**Sequence:**
1. User clicks logout button
2. **Logout Request**: Frontend calls `POST /api/v1/auth/logout`
3. **Cookie Clearing**: Backend clears httpOnly cookies (`accessToken`, `refreshToken`)
4. **Okta Logout**: Frontend redirects to Okta logout endpoint (if ID token available)
5. **Session Termination**: User session is terminated on both application and IdP

**Mermaid Sequence Diagram - Logout Flow:**

```mermaid
sequenceDiagram
    participant User
    participant ReactApp as React Application
    participant Backend as Backend API
    participant Okta as Okta IdP
    participant Browser as Browser Storage
    
    User->>ReactApp: Click logout button
    ReactApp->>Backend: POST /api/v1/auth/logout
    Backend->>Backend: Clear httpOnly cookies (accessToken, refreshToken)
    Backend->>Backend: Log logout activity
    Backend->>ReactApp: 200 OK (logout successful)
    ReactApp->>Browser: Clear localStorage (if any)
    ReactApp->>Okta: Redirect to Okta logout endpoint (with ID token)
    Okta->>Okta: Terminate Okta session
    Okta->>ReactApp: Redirect to application
    ReactApp->>User: Show login page
```

---

## 6. RE Workflow System Flow Diagram

### 6.1 Executive Summary

This document formalizes the technical architecture for the RE Workflow Management System, covering runtime architecture, routing, authentication/SSO, session & data flow, state management, integrations (Okta, GCS), configuration, security posture, error handling, and extensibility.

**High-Level Architecture (Simple View)**

```
User's Web Browser → RE Workflow Application (React) → Backend API (Express) → PostgreSQL Database
                                                              ↓
                                                    Okta Identity Provider (IdP)
                                                              ↓
                                                    Google Cloud Storage (GCS)
```

**Mermaid Diagram - High-Level Architecture:**

```mermaid
graph LR
    Browser[User's Web Browser]
    ReactApp[RE Workflow Application<br/>React]
    BackendAPI[Backend API<br/>Express]
    PostgreSQL[(PostgreSQL Database)]
    Okta[Okta Identity Provider<br/>IdP]
    GCS[Google Cloud Storage<br/>GCS]
    
    Browser -->|HTTPS| ReactApp
    ReactApp -->|API Calls| BackendAPI
    BackendAPI -->|Data Storage| PostgreSQL
    BackendAPI -->|Authentication| Okta
    BackendAPI -->|File Storage| GCS
    ReactApp -->|SSO Login| Okta
```

### 6.2 Technology Stack & Conventions

**Frontend:**
- **Framework**: React 18 with TypeScript
- **Build Tool**: Vite
- **Routing**: React Router v6
- **Styling**: Tailwind CSS; UI primitives via shadcn/ui & Radix
- **State**: Redux Toolkit (authSlice, storeSlice) + React Context (AuthContext)
- **Data Fetching**: Axios with interceptors (token refresh, error handling)
- **Security**: HttpOnly cookies (production) / localStorage (development)

**Backend:**
- **Runtime**: Node.js 22 LTS
- **Language**: TypeScript 5.7
- **Framework**: Express.js 4.21
- **Database**: PostgreSQL 16
- **ORM**: Sequelize 6.37
- **Authentication**: JWT (JSON Web Tokens)
- **Validation**: Zod schemas
- **Logging**: Winston logger
- **Security**: Helmet.js, CORS middleware, cookie-parser

### 6.3 Routing & Layout

**Frontend Routes:**
- `/` or `/dashboard` - Dashboard (authenticated users)
- `/login/callback` - OAuth callback handler
- `/request/:requestId` - Request detail view
- `/new-request` - Create new request
- `/my-requests` - User's requests
- `/open-requests` - Open requests (management/admin)
- `/closed-requests` - Closed requests
- `/admin` - Admin control panel (admin only)
- `/profile` - User profile
- `/settings` - Application settings

**Backend Routes:**
- `/api/v1/auth/*` - Authentication endpoints
- `/api/v1/workflows/*` - Workflow management
- `/api/v1/documents/*` - Document management
- `/api/v1/users/*` - User management
- `/api/v1/activities/*` - Activity logging
- `/health` - Health check endpoint

**Route Protection:**
- **Frontend**: `AuthContext` checks authentication status, redirects to login if not authenticated
- **Backend**: `authenticateToken` middleware validates JWT token on protected routes
- **Role-Based**: `requireRole` middleware enforces role-based access control

### 6.4 Authentication (SSO) & Session

**Login Flow:**
1. User navigates to application
2. Frontend checks for existing session (httpOnly cookie in production, localStorage in development)
3. If no session, redirects to Okta Sign-In Widget
4. User authenticates with Okta (credentials + MFA if enabled)
5. Okta redirects to `/login/callback` with authorization code
6. Frontend calls `/api/v1/auth/token-exchange` with code
7. Backend exchanges code for tokens with Okta
8. Backend creates/updates user in database
9. Backend generates JWT tokens and sets httpOnly cookies (production) or returns tokens (development)
10. User is redirected to dashboard

**Cookie Configuration:**
- **Name**: `accessToken`, `refreshToken`
- **HttpOnly**: `true` (prevents XSS attacks)
- **Secure**: `true` in production (HTTPS only)
- **SameSite**: `lax` (development) / `none` (production for cross-domain)
- **MaxAge**: 24 hours (accessToken), 7 days (refreshToken)
- **Path**: `/`

**Cookie Payload Schema:**
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**JWT Token Payload:**
```json
{
  "userId": "uuid",
  "employeeId": "EMP001",
  "email": "user@royalenfield.com",
  "role": "USER" | "MANAGEMENT" | "ADMIN",
  "iat": 1234567890,
  "exp": 1234654290
}
```

**Cookie Consumers:**
- **Backend Middleware**: `authenticateToken` reads token from cookie or Authorization header
- **Frontend**: Axios automatically sends cookies with `withCredentials: true`
- **Token Refresh**: Automatic refresh via Axios interceptor when access token expires

**Behavior:**
After login, the cookie is validated on each request, driving personalized UI and API authorization. Token refresh happens automatically in the background when access token expires.

### 6.5 Session & Application Data Flow

**Session Endpoints:**
- **GET `/api/v1/auth/me`**: Returns current user profile (validates cookie, fetches user from database)
- **POST `/api/v1/auth/refresh`**: Refreshes access token using refresh token (from cookie or request body)

**Data Flow:**
1. **Request**: Frontend makes API request with httpOnly cookie (production) or Authorization header (development)
2. **Validation**: Backend middleware validates JWT token
3. **User Lookup**: Backend fetches user from database to ensure active status
4. **Authorization**: Backend applies role-based access control
5. **Response**: Backend returns data with appropriate status code

**Error Handling:**
- **401 Unauthorized**: Token missing, invalid, or expired → Frontend triggers token refresh or redirects to login
- **403 Forbidden**: User lacks required role → Frontend shows access denied message
- **500 Internal Server Error**: Backend logs error, returns generic error message to frontend

### 6.6 Security Posture

**Cookies:**
- **HttpOnly**: `true` (prevents JavaScript access, mitigates XSS)
- **Secure**: `true` in production (HTTPS only, prevents man-in-the-middle)
- **SameSite**: `lax` (development) / `none` (production for cross-domain)
- **MaxAge**: 24 hours (accessToken), 7 days (refreshToken)
- **Path**: `/` (available to all routes)

**Headers (Helmet.js):**
- **Content-Security-Policy (CSP)**: Restricts resource loading (scripts, styles, images, connections)
- **X-Frame-Options**: Prevents clickjacking attacks
- **X-Content-Type-Options**: Prevents MIME type sniffing
- **Referrer-Policy**: Controls referrer information
- **Strict-Transport-Security (HSTS)**: Enforces HTTPS in production

**TLS/SSL:**
- **Production**: HTTPS enforced via reverse proxy (Nginx) or load balancer
- **Development**: HTTP allowed for local development
- **Certificate**: Managed via Let's Encrypt or enterprise CA

**Secrets Management:**
- **JWT Secret**: Stored in environment variable (`JWT_SECRET`)
- **Okta Credentials**: Stored in environment variables (`OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`)
- **Database Credentials**: Stored in environment variables (never committed to repository)
- **Recommendation**: Use secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) in production

**Input Validation:**
- **Zod Schemas**: All request bodies validated using Zod schemas
- **SQL Injection Prevention**: Sequelize ORM uses parameterized queries
- **XSS Prevention**: Input sanitization and output encoding

**Rate Limiting:**
- **Recommendation**: Implement rate limiting middleware (express-rate-limit) for authentication endpoints
- **Current**: Not implemented (to be added)

---

## 7. Key Components

### 7.1 User Directory

**Current Implementation:**
- User accounts stored in PostgreSQL database (`users` table)
- Roles: `USER`, `MANAGEMENT`, `ADMIN`
- User data synced from Okta on each login
- Just-in-Time (JIT) provisioning: Users created automatically on first SSO login

### 7.2 User Management

**Okta Integration:**
- Primary identity provider for authentication
- User directory managed in Okta
- User attributes synced to local database on login

**Local Database:**
- User records stored in PostgreSQL
- Fields: `userId`, `email`, `employeeId`, `firstName`, `lastName`, `displayName`, `department`, `designation`, `role`, `isActive`, `oktaSub`
- User creation/update happens automatically on SSO callback

**User Service:**
- `src/services/user.service.ts`: User CRUD operations
- `src/services/auth.service.ts`: User creation/update during SSO callback

### 7.3 Login and Dashboard

**RE Workflow Portal:**
- Unified login experience via Okta Sign-In Widget
- Dashboard provides overview of:
  - Open requests (pending user action)
  - My requests (user-initiated requests)
  - Pending approvals (requests awaiting user approval)
  - System metrics (TAT, completion rates)

**Authentication Flow:**
- Frontend: `src/contexts/AuthContext.tsx` manages authentication state
- Backend: `src/controllers/auth.controller.ts` handles authentication requests
- Okta: Identity provider for user authentication

### 7.4 Database Configuration

**PostgreSQL Database:**
- **Database Name**: `re_workflow_db` (configurable)
- **Tables**: `users`, `workflow_requests`, `documents`, `work_note_attachments`, `activities`, etc.
- **ORM**: Sequelize for database operations
- **Migrations**: Database schema managed via Sequelize migrations

**Database Models:**
- `src/models/User.ts`: User model with authentication fields
- `src/models/WorkflowRequest.ts`: Workflow request model
- `src/models/Document.ts`: Document model with GCS integration
- `src/models/WorkNoteAttachment.ts`: Work note attachment model

### 7.5 File Storage

**Google Cloud Storage (GCS):**
- **Bucket**: `re-workflow-documents` (configurable)
- **Region**: `asia-south1` (configurable)
- **Structure**: `requests/{requestNumber}/{fileType}/{fileName}`
  - `fileType`: `documents` or `attachments`
- **Access**: Public URLs (if `GCP_BUCKET_PUBLIC=true`) or signed URLs
- **Service**: `src/services/gcsStorage.service.ts`

**Local Storage (Fallback):**
- Used when GCS is not configured or upload fails
- Files stored in `uploads/` directory
- Served via Express static middleware

### 7.6 API Access

**OAuth2 Flows:**
- **Authorization Code Flow**: Used by web application (frontend)
- **Resource Owner Password Credentials Flow**: Used by API clients (Postman, mobile apps)

**Service-to-Service Authentication:**
- **Current**: Not implemented (to be added for integrations)
- **Recommendation**: OAuth2 Client Credentials flow for service-to-service authentication

---

## 8. Security Considerations

### 8.1 Multi-Factor Authentication (MFA)

**IdP Configuration:**
- MFA enforced via Okta conditional access policies
- Users required to complete MFA challenge during login
- MFA methods: SMS, TOTP, Push notification (configurable in Okta)

**Application Level:**
- MFA handled entirely by Okta
- Application receives authenticated user info after MFA completion
- No MFA state management required in application

### 8.2 Conditional Access

**IdP Policies:**
- Location-based restrictions (e.g., block access from certain countries)
- Device compliance requirements
- Time-based access restrictions
- IP whitelist/blacklist

**Application Level:**
- Role-based access control (RBAC) enforced via middleware
- Routes protected by `authenticateToken` and `requireRole` middleware
- Frontend route guards prevent unauthorized access

### 8.3 Role Assignments and Permissions

**Roles:**
- **USER**: Standard user, can create requests and participate in workflows
- **MANAGEMENT**: Management user, can view all requests and perform management actions
- **ADMIN**: Administrator, full system access including user management

**Permission Enforcement:**
- **Backend**: `requireRole` middleware enforces role-based access
- **Frontend**: `hasManagementAccess` helper function checks user role
- **Database**: Role stored in `users.role` column

**Regular Review:**
- **Recommendation**: Implement periodic role review process
- **Audit**: All role changes logged in `activities` table

### 8.4 Audit Logging

**Application Logging:**
- **Winston Logger**: Structured logging for all application events
- **Activity Logging**: All user actions logged in `activities` table
- **Authentication Events**: Login, logout, token refresh logged with user info and IP address

**IdP Logging:**
- **Okta System Log**: All authentication events logged in Okta
- **Azure Entra Audit Logs**: (Future) User access and role changes logged

**Log Retention:**
- **Recommendation**: Retain logs for 90 days (configurable)
- **Compliance**: Logs retained per organizational compliance requirements

### 8.5 Token Security

**JWT Token Security:**
- **Secret**: Strong secret key stored in environment variable
- **Expiry**: Short-lived access tokens (24 hours), longer-lived refresh tokens (7 days)
- **Signature**: HMAC SHA-256 algorithm
- **Validation**: Token signature and expiry validated on each request

**Cookie Security:**
- **HttpOnly**: Prevents JavaScript access (mitigates XSS)
- **Secure**: HTTPS only in production (mitigates man-in-the-middle)
- **SameSite**: CSRF protection

**Token Refresh:**
- **Automatic**: Frontend automatically refreshes expired tokens
- **Secure**: Refresh token validated before issuing new access token
- **Rotation**: (Future) Implement refresh token rotation for enhanced security

---

## 9. Provisioning & Lifecycle

### 9.1 User Provisioning

**Current Implementation:**
- **Just-in-Time (JIT) Provisioning**: Users created automatically on first SSO login
- **User Data Source**: Okta user directory
- **Sync Frequency**: Real-time (on each login)

**User Creation Flow:**
1. User authenticates with Okta
2. Backend receives user info from Okta
3. Backend checks if user exists in database (by email)
4. If user exists, updates user record with latest info from Okta
5. If user doesn't exist, creates new user record with default role `USER`
6. User is granted access to application

**Mermaid Sequence Diagram - User Provisioning Flow:**

```mermaid
sequenceDiagram
    participant User
    participant Okta as Okta IdP
    participant Backend as Backend API
    participant AuthService as Auth Service
    participant DB as PostgreSQL Database
    
    User->>Okta: Authenticate (credentials + MFA)
    Okta->>Okta: Validate credentials
    Okta->>Backend: Return authorization code
    Backend->>Okta: Exchange code for tokens
    Okta->>Backend: Return access token + user info
    Backend->>AuthService: handleSSOCallback(userData)
    AuthService->>DB: Check if user exists (by email)
    
    alt User exists
        DB->>AuthService: User found
        AuthService->>DB: Update user record (displayName, department, etc.)
        DB->>AuthService: User updated
    else User doesn't exist
        DB->>AuthService: User not found
        AuthService->>DB: Create new user (role: USER, isActive: true)
        DB->>AuthService: User created
    end
    
    AuthService->>AuthService: Generate JWT tokens
    AuthService->>Backend: Return tokens + user data
    Backend->>User: Set cookies + redirect to dashboard
```

**User Update Flow:**
- User attributes updated on each login
- Fields updated: `displayName`, `department`, `designation`, `phone`, `lastLogin`
- `oktaSub` updated if changed in Okta

### 9.2 SCIM Provisioning (Future)

**Recommendation**: Implement SCIM 2.0 for automated user provisioning

**Benefits:**
- Automated user creation from HRMS
- Automatic role assignments based on HRMS data
- User deprovisioning when user is removed from HRMS
- Group/role synchronization

**Implementation:**
- **SCIM Endpoint**: `/api/v1/scim/v2/Users`
- **SCIM Provider**: Okta or Azure Entra
- **SCIM Client**: HRMS system

### 9.3 User Deprovisioning

**Current Implementation:**
- **Manual Deactivation**: Admin can deactivate user via admin panel
- **Field**: `users.isActive` set to `false`
- **Effect**: User cannot authenticate (middleware checks `isActive` status)

**Future Implementation:**
- **Automatic Deprovisioning**: User deactivated when removed from Okta
- **SCIM Integration**: User deprovisioned via SCIM DELETE request
- **Data Retention**: User data retained for audit purposes (soft delete)

### 9.4 Group/Role Assignments

**Current Implementation:**
- **Default Role**: New users assigned `USER` role
- **Manual Assignment**: Admin can change user role via admin panel
- **Role Storage**: Role stored in `users.role` column

**Future Implementation:**
- **Okta Group Mapping**: Map Okta groups to application roles
- **Automatic Assignment**: Assign roles based on Okta group membership
- **HRMS Integration**: Assign roles based on HRMS job title/department

### 9.5 Lifecycle Management

**User Onboarding:**
1. User added to Okta directory (by IT admin)
2. User receives welcome email with application URL
3. User logs in via Okta SSO
4. User account created automatically in application
5. User assigned default role `USER`
6. User can access application

**User Offboarding:**
1. User removed from Okta directory (by IT admin)
2. User cannot authenticate (Okta rejects login)
3. User account remains in database (for audit)
4. Admin can manually deactivate user account
5. User data retained per retention policy

**Role Changes:**
1. Admin updates user role in admin panel
2. Role change logged in `activities` table
3. User permissions updated immediately (no logout required)
4. Role change synced to database

---

## 10. SSO Implementation Activity Tracker

This section tracks SSO implementation activities specific to the RE Workflow Management System.

| Sr | Activity | Owner | Status | Remarks |
|----|----------|-------|--------|---------|
| 1 | Okta Application Configuration | - | Completed | OAuth 2.0 / OIDC application configured |
| 2 | Backend SSO Integration | - | Completed | Token exchange endpoint implemented |
| 3 | Frontend SSO Integration | - | Completed | Okta Sign-In Widget integrated |
| 4 | JWT Token Implementation | - | Completed | Access and refresh tokens configured |
| 5 | HttpOnly Cookie Implementation | - | Completed | Secure cookie-based authentication |
| 6 | User Provisioning (JIT) | - | Completed | Automatic user creation on first login |
| 7 | Token Refresh Mechanism | - | Completed | Automatic token refresh implemented |
| 8 | Role-Based Access Control | - | Completed | USER, MANAGEMENT, ADMIN roles implemented |
| 9 | GCS Integration for Documents | - | Completed | Google Cloud Storage configured |
| 10 | Audit Logging | - | Completed | Authentication events logged |
| 11 | Domain Configuration | - | Pending | Configure production domain |
| 12 | Production Deployment | - | Pending | Deploy to production environment |
| 13 | MFA Enforcement | - | Pending | Configure MFA policies in Okta |
| 14 | SCIM Provisioning | - | Future | Automated user provisioning from HRMS |
| 15 | Session Management Dashboard | - | Future | Active session tracking and management |

---

## 11. Configuration Reference

### 11.1 Environment Variables

**Backend (.env):**
```env
# Server
NODE_ENV=production
PORT=5000
FRONTEND_URL=https://rebridge.co.in

# Database
DB_HOST=postgresql-host
DB_PORT=5432
DB_NAME=re_workflow_db
DB_USER=postgres
DB_PASSWORD=secure_password

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRY=24h
REFRESH_TOKEN_EXPIRY=7d

# Okta
OKTA_DOMAIN=https://dev-830839.oktapreview.com
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret

# GCS
GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_BUCKET_NAME=re-workflow-documents
GCP_KEY_FILE=./config/gcp-key.json
GCP_BUCKET_REGION=asia-south1
GCP_BUCKET_PUBLIC=true
```

**Frontend (.env):**
```env
VITE_API_BASE_URL=https://api.rebridge.co.in/api/v1
VITE_OKTA_DOMAIN=https://dev-830839.oktapreview.com
VITE_OKTA_CLIENT_ID=your-client-id
```

### 11.2 Okta Application Configuration

**Application Type**: Single-Page App (SPA)
**Grant Types**: 
- Authorization Code
- Refresh Token
**Redirect URIs**:
- Production: `https://rebridge.co.in/login/callback`
- Development: `http://localhost:3000/login/callback`
**Logout Redirect URI**:
- Production: `https://rebridge.co.in`
- Development: `http://localhost:3000`

### 11.3 Database Schema

**Users Table:**
```sql
CREATE TABLE users (
  user_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  employee_id VARCHAR(50),
  okta_sub VARCHAR(255) UNIQUE,
  first_name VARCHAR(100),
  last_name VARCHAR(100),
  display_name VARCHAR(200),
  department VARCHAR(100),
  designation VARCHAR(100),
  phone VARCHAR(20),
  role VARCHAR(20) DEFAULT 'USER' CHECK (role IN ('USER', 'MANAGEMENT', 'ADMIN')),
  is_active BOOLEAN DEFAULT true,
  last_login TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## 12. Troubleshooting

### 12.1 Common Issues

**Issue: "Token has expired"**
- **Cause**: Access token expired (24 hours)
- **Solution**: Token should refresh automatically. If not, check refresh token validity.

**Issue: "User not found or inactive"**
- **Cause**: User account deactivated or removed from database
- **Solution**: Check `users.isActive` status. Reactivate user if needed.

**Issue: "Invalid token"**
- **Cause**: Token signature invalid or JWT secret mismatch
- **Solution**: Verify `JWT_SECRET` matches between environments.

**Issue: "Okta authentication failed"**
- **Cause**: Invalid Okta credentials or network issue
- **Solution**: Verify `OKTA_CLIENT_ID` and `OKTA_CLIENT_SECRET`. Check Okta domain accessibility.

**Issue: Cookies not being set**
- **Cause**: Cookie options mismatch or CORS configuration
- **Solution**: Verify `FRONTEND_URL` matches frontend domain. Check `withCredentials: true` in Axios config.

### 12.2 Debugging

**Enable Debug Logging:**
```env
LOG_LEVEL=debug
```

**Check Token Validity:**
```bash
# Decode JWT token (without verification)
echo "YOUR_TOKEN" | base64 -d
```

**Verify Cookie Settings:**
- Check browser DevTools → Application → Cookies
- Verify `HttpOnly`, `Secure`, `SameSite` flags
- Check cookie `Path` and `Domain`

**Test Authentication Flow:**
1. Clear browser cookies and localStorage
2. Navigate to application
3. Complete Okta login
4. Check network tab for `/api/v1/auth/token-exchange` request
5. Verify cookies are set in response headers
6. Check subsequent API requests include cookies

---

## 13. Future Enhancements

### 13.1 Planned Features

1. **SCIM 2.0 Provisioning**: Automated user provisioning from HRMS
2. **Refresh Token Rotation**: Enhanced security for token refresh
3. **Rate Limiting**: Protect authentication endpoints from brute force
4. **Session Management**: Active session tracking and management
5. **Device Management**: Track and manage user devices
6. **Audit Dashboard**: Visual interface for authentication and access logs

### 13.2 Integration Opportunities

1. **Azure Entra Integration**: Federation with Azure Entra for enterprise SSO
2. **Tanflow Integration**: Full integration with Tanflow IdP
3. **HRMS Integration**: Direct integration with HRMS for user data
4. **Active Directory Integration**: LDAP/AD integration for on-premises users

---

## Document Version

- **Version**: 1.0
- **Last Updated**: December 2024
- **Author**: RE Workflow Development Team
- **Review Status**: Draft

---

## Appendix

### A. Glossary

- **IdP**: Identity Provider (Okta, Tanflow)
- **SSO**: Single Sign-On
- **JWT**: JSON Web Token
- **OAuth 2.0**: Authorization framework
- **OIDC**: OpenID Connect
- **SAML**: Security Assertion Markup Language
- **SCIM**: System for Cross-domain Identity Management
- **MFA**: Multi-Factor Authentication
- **RBAC**: Role-Based Access Control
- **CSP**: Content Security Policy
- **HSTS**: HTTP Strict Transport Security

### B. References

- [Okta Developer Documentation](https://developer.okta.com/docs/)
- [OAuth 2.0 Specification](https://oauth.net/2/)
- [OpenID Connect Specification](https://openid.net/connect/)
- [JWT.io](https://jwt.io/)
- [SCIM 2.0 Specification](https://www.rfc-editor.org/rfc/rfc7644)

---

**End of Document**