← Back to Docs

Architecture

SSO Server architecture and design overview

Overview

The Simpliciti SSO Server is a Node.js/Express application that provides Single Sign-On (SSO) functionality by integrating multiple Identity Providers (IdPs) with multiple external applications.

Core Components

Authentication Flow

  • OAuth/OIDC Providers: Google, GitLab, Keycloak, Auth0
  • SAML Provider: Enterprise SAML authentication with SP proxy mode
  • Skip-Auth Flow: Token-based authentication bypass for linked applications
  • UI Mode: Admin interface authentication

Key Services

  • Authentication Service (src/utils/auth.js): Core authentication logic
  • SAML Service (src/services/saml/): SAML-specific authentication handling
  • Token Service (src/utils/ssoToken.js): SSO token generation and verification
  • Routing Service (src/utils/routing.js): Dynamic redirect URL construction

Data Models

  • ClientConfig: Provider configurations (OAuth/SAML settings)
  • Application: External application definitions
  • UserLink: User-account linking between IdP and external apps
  • SsoLog: Authentication attempt logging

Authentication Modes

Standard OAuth/OIDC Flow

  1. User initiates auth via /auth/authorize/config/:configId/:appId
  2. Redirect to IdP for authentication
  3. Callback to /auth/callback with authorization code
  4. Exchange code for user details and external token
  5. Redirect to external application with token

SAML Flow

  1. Initiate SAML request via /auth/saml/:providerId/:appId
  2. Redirect to SAML IdP with AuthnRequest
  3. IdP POSTs SAMLResponse to /auth/saml/callback
  4. Validate SAML assertion and extract user details
  5. Redirect to external application or forward raw assertion (SP proxy mode)

Skip-Auth Flow

  1. Direct entry via /auth/direct-skip?clientId=X&applicationId=Y
  2. Check for existing UI session
  3. If authenticated, generate short-lived SSO token
  4. Redirect to application with SSO token
  5. Application verifies token via /auth/verify-sso-token

State Management

Session Storage

  • Store: MongoDB via connect-mongo
  • TTL: 7 days
  • Key Session Variables:
    • auth_attempt_id: Unique attempt identifier
    • uiAuth[configId]: UI authentication state
    • samlRequestId: SAML request tracking
    • directSkipIntent: Skip-auth flow state

SAML State

  • DB-Backed State: MongoDB collection for SAML RelayState
  • Fallback: Session storage for resilience
  • Purpose: Prevents RelayState truncation by IdPs like Keycloak

Security Features

Token Management

  • SSO Tokens: Short-lived JWT tokens for skip-auth flow
  • IdP Token Caching: Server-side caching of raw IdP tokens
  • Token Verification: Public endpoint for external app validation

CSP Integration

  • Nonce Support: CSP nonce injection in all forms
  • Configurable: Environment-based CSP policy
  • Security Headers: Content-Security-Policy enforcement

SAML Security

  • Assertion Validation: Timing, audience, and signature verification
  • Replay Protection: Request ID tracking with timeout
  • Signing Utilities: Assertion signing and verification

Deployment

Docker Support

  • Coolify Integration: Automated deployment scripts
  • Versioned Tags: Semantic versioning for Docker images
  • Environment Configuration: .env based configuration

Development

  • Hot Reload: Nodemon for development
  • Testing: Jest with 15s timeout
  • Linting: ESLint with auto-fix

Integration Points

External Application Integration

  • GET/POST Redirects: Flexible redirect methods
  • Hash Routing: Support for SPA hash-based routing
  • Encoded Parameters: Special parameter validation and encoding
  • Dynamic Payload: Custom parameter passing

IdP Integration

  • OAuth 2.0: Standard OAuth2 flow
  • OpenID Connect: OIDC protocol support
  • SAML 2.0: Enterprise SAML with SP proxy mode
  • Provider Adapters: Pluggable provider architecture

Monitoring & Logging

SSO Logging

  • Attempt Tracking: auth_attempt_id for request correlation
  • Event Types: Authentication start, callback, redirect, errors
  • Metadata: Provider, application, configuration details
  • Audit Trail: Complete authentication flow logging

Debug Mode

  • SAML Debug: Raw SAML response capture
  • Request Logging: Detailed request/response logging
  • Error Tracking: Comprehensive error handling and logging