feat: Enterprise SSO Support with POST Authentication and Session Security

[billchurch]

Summary

Implements comprehensive enterprise Single Sign-On (SSO) authentication via secure HTTP POST requests, enabling seamless integration with identity providers like F5 BIG-IP APM, SAML providers, and other enterprise authentication systems.

Key Features

✅ POST Authentication Endpoint: New POST /ssh/host/:host route for form-based authentication
✅ Session-Only Security: Credentials stored server-side in HTTPOnly sessions, never exposed to client
✅ Enterprise SSO Integration: Support for custom authentication headers (X-APM-Username, X-APM-Password)
✅ CSRF Protection: Configurable CSRF token validation with trusted proxy support
✅ Zero Client Exposure: No passwords, usernames, or keys sent to browser JavaScript
✅ Backward Compatibility: Existing GET routes and Basic Auth continue to work unchanged

Security Enhancements

🔒 Session-Based Credentials: All authentication data stored in encrypted server sessions
🔒 CSRF Token Validation: Optional protection against cross-site request forgery
🔒 Trusted Proxy Whitelist: IP-based access control for enterprise environments
🔒 HTTPOnly Sessions: Credentials inaccessible to client-side JavaScript
🔒 Configurable Session Secrets: Encrypted session storage with custom keys

Configuration Support

⚙️ Dual Configuration: Support for both environment variables (WEBSSH2_SSO_*) and config.json
⚙️ Environment Priority: Environment variables override config.json values
⚙️ Flexible Header Mapping: Configurable authentication header names for different SSO providers
⚙️ Production Ready: Full environment variable support for containerized deployments

Changes Made

Core Authentication

• app/routes.js: Added POST /ssh/host/:host endpoint with session-based auth
• app/middleware.js: Implemented POST authentication middleware with CSRF protection
• app/socket.js: Extended session credential retrieval for WebSocket connections
• app/security-headers.js: Enhanced security headers for SSO environments

Configuration & Environment

• app/envConfig.js: Added comprehensive SSO environment variable mapping
• app/config.js: Added SSO configuration defaults with dual config support
• app/constants.js: Added SSO-related constants and headers

Testing & Documentation

• tests/post-auth.test.js: Comprehensive test suite for POST authentication flows
• DOCS/SSO-Implementation.md: Complete implementation guide with examples
• examples/sso-bigip-apm.html: Working F5 BIG-IP APM integration example

Test Coverage

• ✅ POST authentication with valid credentials
• ✅ Session-based credential storage and retrieval
• ✅ CSRF token validation and protection
• ✅ Custom header authentication (X-APM-Username/Password)
• ✅ Trusted proxy validation
• ✅ Error handling and security edge cases
• ✅ WebSocket session integration

Files Changed

• 15 files modified, 1,655 lines added, 38 lines removed
• New documentation: SSO implementation guide and examples
• New tests: Comprehensive POST authentication test suite
• Enhanced security: Session management and CSRF protection
• Extended configuration: Full environment variable support

Deployment Notes

This change is fully backward compatible. Existing Basic Auth and GET routes continue to work unchanged. New SSO functionality requires configuration to enable:

# Enable SSO (optional - defaults to disabled)
export WEBSSH2_SSO_ENABLED=true

# Configure authentication headers (optional - has defaults)
export WEBSSH2_SSO_USERNAME_HEADER=X-APM-Username
export WEBSSH2_SSO_PASSWORD_HEADER=X-APM-Password

Integration Examples

• F5 BIG-IP APM: Complete working example in `examples/sso-bigip-apm.html`
• SAML Providers: Generic POST form integration pattern
• Custom SSO: Flexible header-based authentication support

[sonarqubecloud]

Quality Gate failed

Failed conditions
16.7% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud