SSO Client Module

The SSO Client module transparently proxies user authentication and profile operations to an SSO server when anchored, while evaluating permissions locally using the client instance's own group and context definitions.

Overview

This module provides seamless centralized authentication with local authorization. User identity operations (login, registration, profile updates) are proxied to the SSO server, while Doh.permit() checks run entirely on the local instance against locally-defined permission groups and contexts.

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
• Auth Proxy + Local Permissions: User identity proxied to SSO; permissions evaluated locally
• 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 Evaluation (Local)

• Doh.permit() → Evaluated locally using the client's own Doh.PermissionGroups and Doh.PermissionContexts
• After receiving a user from SSO, Doh.loadUserPermissionGroups() runs locally to populate groups from local definitions
• The SSO server does NOT send groups — they are always computed on the client

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 and connection status with SSO server details
• See architecture overview (what's proxied vs evaluated locally)
• View operation routing — which user operations go to SSO, which stay local
• Anchor or re-anchor to the SSO server
• Clear anchoring to revert to local authentication
• View anchor details (creation date, fingerprint, last used)
• Review all pod configuration settings

The interface uses the admin dashboard theme and provides the same core functionality as the CLI.

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
• Each instance defines its own permission groups for local features
• Easy deployment of new instances
• Seamless user experience across all entrances

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:

Anchoring

• performSSOAnchoring(username, password) - Anchor to SSO server
• performSSOAnchoringAs(requestingUser, requestingPassword, targetUser) - Anchor-as
• isInstanceSSOAnchored() - Check if anchored
• clearSSOAuthToken() - Clear authentication token
• clearSSOAnchor() - Clear anchor data

Anchor Data

• loadSSOAnchor() - Load stored anchor data (fingerprint, created, lastUsed)
• storeSSOAnchor(fingerprint, originalFingerprint?) - Store anchor data
• getSSOFingerprint() - Get instance fingerprint

Cache Management

• clearUserCache() - Clear all cached user data
• refreshUserCache(user) - Refresh cache for a specific user

Connection

• getConnectionStatus() - Returns current connection state ('connected', 'disconnected', 'unknown')

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