SSO Client Module

The SSO Client module transparently proxies ALL user operations to an SSO server when anchored. This enables Doh instances to operate with zero local users while seamlessly accessing a centralized user system.

Overview

This module provides 100% transparent user database sharing by intercepting all user operations and proxying them to a central SSO server. Users, admins, and applications never know authentication is remote.

Key Features

• Complete Transparency: Zero code changes needed - existing applications work unchanged
• Cold Instance Deployment: Edge instances can start with NO users and work immediately
• Transparent Proxy: Every user operation is seamlessly proxied to SSO server
• Advanced Caching: Multi-level caching system prevents repeated SSO calls
• Token Validation Cache: 3-minute cache for token validation to eliminate validation spam
• User Data Cache: Intelligent user data caching for optimal performance
• Fallback Support: Optional fallback to local users when SSO server unavailable
• CLI Management: Full command-line interface for anchoring management
• Admin Interface: Web-based anchoring management
• Persistent Anchors: Anchor tokens never expire, matching cloud system behavior

Configuration

Configure SSO Client in your pod.yaml:

sso_client:
  endpoint: "https://your-sso-server.com"
  fallback_to_local: true
  debug_logging: false

Pod Configuration Options

CLI Commands

The module provides a complete CLI interface mirroring cloud anchoring patterns:

Basic Commands

# Set SSO endpoint
doh sso endpoint <sso-server-url>

# Anchor to SSO server with your credentials
doh sso anchor

# Set endpoint and anchor in one command
doh sso anchor <sso-server-url>

# Anchor on behalf of another user (requires permissions)
doh sso anchor-as <user@sso-server.com>

# Show anchoring status
doh sso status

# Clear anchoring (revert to local users)
doh sso clear

# Show available commands
doh sso

Example Usage

# Configure and anchor to SSO server
doh sso endpoint https://sso.company.com
doh sso anchor

# Check status
doh sso status

# Clear anchoring if needed
doh sso clear

Transparent User Operations

When anchored, the following user operations are transparently proxied:

Core User Operations

• Users.authenticateUser() → SSO server authentication
• Users.getUserByUsername() → SSO server user lookup
• Users.createUser() → SSO server user creation
• Users.updateUser() → SSO server user updates
• Users.deleteUser() → SSO server user deletion
• Users.getAllUsers() → SSO server user listing

Permission Operations

• Doh.permit() → SSO server permission checks

Fallback Behavior

When fallback_to_local is enabled (default), the client will:

1. Try SSO operation first
2. If SSO server unavailable or authentication fails, fall back to local operations
3. If not anchored, use local operations directly

This ensures resilience and allows graceful degradation.

Performance & Caching

The SSO Client implements a sophisticated multi-level caching system to optimize performance:

Token Validation Cache

• Duration: 3 minutes per token
• Purpose: Prevents repeated validation calls for the same JWT token
• Impact: Eliminates validation spam (e.g., 26+ rapid calls reduced to 1)
• Automatic: Tokens are automatically cached and expired

User Data Cache

• Duration: Session-based with manual invalidation
• Purpose: Prevents repeated user data fetches from SSO server
• Cache Strategy:
  • First call fetches from SSO server and caches result
  • Subsequent calls return cached data immediately
  • Cache cleared on user updates to ensure consistency

Anchoring Status Cache

• Duration: 30 seconds
• Purpose: Avoids repeated file system checks for anchor status
• Automatic: Refreshes automatically when status changes

Performance Benefits

• Reduced Latency: Cached operations return in microseconds vs network round-trips
• Server Load: Dramatically reduces load on SSO server
• Network Usage: Minimizes bandwidth consumption
• User Experience: Faster page loads and response times

Cache Management

// Programmatic cache control
Doh.SSOAnchoring.clearUserCache();        // Clear user data cache
Doh.SSOAnchoring.refreshUserCache(user);  // Refresh specific user

Cache is automatically managed but can be controlled when needed.

Admin Interface

Access the admin interface at /admin/sso_anchoring to:

• View anchoring status
• Anchor/re-anchor to SSO server
• Clear anchoring
• View configuration details

The interface provides the same functionality as the CLI but through a web UI.

Permission System

The module defines the following permission group:

sso_user Group

Permissions:

• manage:sso_anchoring - Can anchor/unanchor instances
• view:sso_anchoring - Can view SSO connection interface

To assign SSO user permissions:

// Via code
Doh.assignUserToPermissionGroup(user, 'sso_user');

Or via pod configuration:

Users:
  groups:
    sso_user:
      inherits: ['authenticated_user']
      permissions:
        - 'manage:sso_anchoring'
        - 'view:sso_anchoring'

Security Features

• Secure Token Storage: Auth tokens stored with restricted file permissions
• Credential Protection: SSO credentials never stored, used once and discarded
• Instance Fingerprinting: Persistent instance identification
• Automatic Token Management: Handles token lifecycle automatically

Cold Instance Deployment

This module enables "cold" instance deployment:

1. Deploy new Doh instance with zero users
2. Install and configure SSO client module
3. Anchor to SSO server: doh sso anchor https://sso.company.com
4. Instance immediately has access to entire organizational user system

No user migration, database setup, or configuration required!

Example Deployment Scenario

Organization Setup:

1. One Doh instance configured as SSO server with all users
2. Multiple edge instances deployed with SSO client
3. All instances share the same user database transparently

Benefits:

• Centralized user management
• Consistent permissions across all instances
• Easy deployment of new instances
• No data duplication or synchronization

Error Handling & Troubleshooting

The module provides comprehensive error handling and diagnostic capabilities:

Common Issues & Solutions

"Endpoint not supported via socket" Error

• Cause: Client attempting to call non-existent SSO server endpoints
• Solution: Ensure SSO server supports all required endpoints
• Fixed: Client now uses correct /api/sso/user/profile/ endpoint

Excessive Validation Calls

• Symptoms: 26+ rapid token validation calls for single page
• Cause: Missing or ineffective caching
• Solution: Multi-level caching system implemented automatically

"Cannot read properties of undefined (reading 'replace')" Error

• Cause: Missing user-agent headers in socket requests
• Solution: Proper browser user-agent headers now provided automatically

Debug Configuration

Enable comprehensive debugging in pod.yaml:

sso_client:
  debug_logging: true

browser_pod:
  Users:
    auth_debug: true    # Enable authentication debug messages

Error Categories

Network Errors

• Connection timeouts and failures
• SSO server unavailable
• Invalid endpoints

Authentication Errors

• Invalid credentials or expired tokens
• Permission denied scenarios
• Token validation failures

Configuration Errors

• Missing SSO endpoint
• Invalid pod configuration
• Permission setup issues

Automatic Recovery

The module includes automatic recovery mechanisms:

• Cache invalidation on errors
• Graceful fallback when configured
• Automatic retry for transient failures
• Connection management for socket issues

API Reference

The module exposes functions via Doh.SSOAnchoring:

• performSSOAnchoring(username, password) - Anchor to SSO server
• performSSOAnchoringAs(requestingUser, requestingPassword, targetUser) - Anchor-as
• isInstanceSSOAnchored() - Check if anchored
• clearSSOAuthToken() - Clear authentication
• getSSOFingerprint() - Get instance fingerprint

These functions are used by the CLI and admin interface but can also be called programmatically.