SurePassID Authentication Server

On-Prem Installer

Overview

The AdminCustomInstall application is a Windows Forms-based installation wizard for SurePassID authentication systems. When deployed in Local environments (non-Azure), the application provides a complete installation wizard for on-premises or traditional virtual machine deployments with full administrative control over all components.

Local Environment Detection

The application automatically detects Local environments by:

• Attempting to query the Azure Instance Metadata Service (IMDS)
• If IMDS is not accessible or returns no data, the environment is classified as InstallEnvironment.Local
• Configuring the complete installation wizard for on-premises deployment

Local Installation Features

Full Installation Wizard

Local environments receive the complete 8-step installation wizard with comprehensive configuration options for on-premises deployments.

Complete Administrative Control

• Full control over database configuration and creation
• Local certificate management and SSL/TLS configuration
• Complete DNS and networking configuration
• Local Key Vault or file-based encryption key management
• Direct IIS configuration and management

Local Installation Flow

Initial Setup and Detection

When launching the application in a Local environment:

1. Environment Check:

   Checking Azure availability for Azure cloud endpoint...

   • The application attempts to query Azure IMDS
   • When no response is received, environment defaults to Local
   • No Azure-specific features are enabled

2. Installation Initialization:

   • Proceeds directly to the full installation wizard
   • No VLE (Virtual Lab Environment) initialization required
   • All 8 wizard steps are available

Complete Installation Wizard Steps

Step 1: Installation Wizard

Main installation introduction and overview

• Welcome message and installation overview
• System requirements validation
• Environment detection confirmation
• Installation path configuration

Step 2: Customize Account

Service and account configuration

• Service account configuration for SurePassID services
• Windows authentication options
• Service startup configuration
• Security context settings

Step 3: SurePassID Services (DNS Configuration)

Network and DNS configuration for all services

Required Hostnames:

• MFA Server Hostname: Primary authentication server (e.g., mfa.yourcompany.com)
• API Server Hostname: REST API endpoint (e.g., api.yourcompany.com)
• SurePassID One IdP Hostname: Unified SAML 2.0, OIDC, and Entra EAM identity provider (e.g., idp.yourcompany.com)
• Legacy SAML2 Alias: Transitional alias for existing integrations (e.g., saml2.yourcompany.com)

DNS Options:

• Update Host File: Automatically update local Windows hosts file for testing
• Allow HTTP: Enable HTTP connections (not recommended for production)

Important: If you don't check "Update host file", you must configure DNS entries for all hostnames before applications can connect to the system.

Step 4: Define Users

Initial user account setup

• Create administrative user accounts
• Set user permissions and roles
• Configure initial authentication methods
• Define user access policies

Step 5: Create Database

Database configuration and creation

Database Options:

• SQL Server Instance: Local or remote SQL Server connection
• Database Creation: Create new database or use existing
• Authentication: Windows Authentication or SQL Server Authentication
• Connection String: Configure database connectivity parameters

Database Requirements:

• SQL Server 2016 or later
• Sufficient permissions to create databases and users
• Network connectivity to database server
• Adequate storage space for SurePassID database

Step 6: SMS & Voice Notifications

Twilio configuration for SMS and voice notifications

Configuration Parameters:

• Account SID: Twilio account identifier
• Auth Token: Twilio authentication token
• Phone Number: Twilio phone number for outbound calls/SMS
• Webhook URL: Callback URL for Twilio responses

Optional Configuration: Leave blank to disable SMS/voice notifications

Step 7: Set Email Notifications

SMTP configuration for email notifications

SMTP Settings:

• SMTP Server: Mail server hostname or IP address
• Port: SMTP port (typically 25, 587, or 465)
• Authentication: Username and password if required
• Encryption: TLS/SSL encryption options
• From Address: Default sender email address

Step 8: Setup Key Vault

Encryption key management configuration

Local Key Management:

• File-Based Storage: Store encryption keys in encrypted configuration files
• Key Generation: Generate new cryptographically secure keys
• Key Rotation: Configure automatic key rotation policies
• Backup Options: Set up key backup and recovery procedures

Azure Key Vault Integration (Optional):

• Connect to Azure Key Vault for centralized key management
• Requires Azure subscription and proper authentication
• Environment variables for Azure authentication must be configured

Step 9: Specify License File

SurePassID licensing configuration

• License File Path: Browse to locate SurePassID license file
• License Validation: Verify license is valid and not expired
• Feature Activation: Enable licensed features based on license type
• Demo License: Option to use demo license for evaluation

Local Environment Advantages

Complete Control

• Full administrative access to all system components
• Direct configuration of IIS, SQL Server, and Windows services
• Local certificate management and SSL/TLS configuration
• Custom networking and firewall configuration

Flexibility

• Support for hybrid cloud scenarios
• Integration with existing on-premises infrastructure
• Custom authentication providers (Active Directory, LDAP)
• Flexible deployment topologies

Security

• Data remains within organization boundaries
• Direct control over encryption keys and certificates
• Custom security policies and compliance requirements
• Air-gapped deployment support

Prerequisites for Local Installation

System Requirements

• Operating System: Windows Server 2016 or later / Windows 10/11
• IIS: Internet Information Services with ASP.NET support
• .NET Framework: .NET Framework 4.8 or later
• SQL Server: SQL Server 2016 or later (local or remote)

Network Requirements

• DNS Resolution: Ability to configure DNS for service hostnames
• Firewall: Appropriate ports open for web services (80, 443)
• Database Connectivity: Network access to SQL Server instance
• Internet Access: For external services (Twilio, SMTP) if configured

Permissions Required

• Local Administrator: Administrative rights on installation server
• SQL Server: Database creation and user management permissions
• IIS Manager: Rights to create and configure IIS applications
• Certificate Store: Permissions to install and manage certificates

Optional Components

• Twilio Account: For SMS and voice notifications
• SMTP Server: For email notifications
• Azure Subscription: For Azure Key Vault integration
• SSL Certificates: For HTTPS/TLS encryption

Installation Process

Pre-Installation Steps

1. System Preparation:

   • Install Windows Server with IIS and ASP.NET features
   • Install SQL Server or ensure database connectivity
   • Configure firewall and network settings
   • Obtain SSL certificates if using HTTPS

2. Service Accounts:

   • Create dedicated service accounts for SurePassID services
   • Configure appropriate permissions and policies
   • Test service account authentication

3. Database Preparation:

   • Install or configure SQL Server
   • Create database instance if not using installer creation
   • Test database connectivity and permissions

Installation Execution

1. Launch Installer: Run AdminCustomInstall.exe as Administrator
2. Complete Wizard Steps: Follow each wizard step in sequence
3. Review Configuration: Verify all settings before proceeding
4. Installation: Click "Start" to begin system configuration
5. Verification: Test system functionality after completion

Post-Installation Steps

1. DNS Configuration:

   • Update DNS records for service hostnames
   • Test hostname resolution from client machines
   • Configure load balancers if using multiple servers

2. SSL Certificate Installation:

   • Install SSL certificates in IIS
   • Configure HTTPS bindings for all services
   • Test SSL certificate validity and chain

3. Service Configuration:

   • Verify Windows services are running
   • Check IIS application pools and sites
   • Test service authentication and permissions

4. Integration Testing:

   • Test MFA authentication workflows
   • Verify API connectivity and responses
     • Test SurePassID One IdP SAML 2.0, OIDC, and Entra EAM functionality

Configuration Management

Configuration Files

• web.config: Main application configuration
• appsettings.json: Modern application settings (for .NET Core components)
• Machine.config: System-wide .NET configuration
• IIS Configuration: ApplicationHost.config

Database Configuration

• Connection Strings: Stored in encrypted configuration sections
• Encryption Keys: Local storage or Azure Key Vault integration
• Database Schema: Automatically created and maintained

Service Configuration

• Windows Services: Configured for automatic startup
• IIS Applications: Application pools and virtual directories
• SSL Bindings: HTTPS configuration and certificate bindings

Troubleshooting Local Installation

Common Installation Issues

IIS Configuration Problems

• Issue: Application pool failures or permission errors
• Solutions:
  • Verify IIS features are installed (.NET Framework support)
  • Check application pool identity and permissions
  • Ensure ASP.NET is properly registered in IIS
  • Review IIS logs for specific error details

Database Connection Issues

• Issue: Cannot connect to SQL Server
• Solutions:
  • Verify SQL Server is running and accessible
  • Check connection string syntax and credentials
  • Test database connectivity using SQL Server Management Studio
  • Verify firewall allows SQL Server traffic (port 1433)

DNS Resolution Problems

• Issue: Service hostnames cannot be resolved
• Solutions:
  • Update hosts file for local testing
  • Configure DNS A records for service hostnames
  • Verify DNS server configuration and propagation
  • Test hostname resolution using nslookup or ping

Certificate and SSL Issues

• Issue: SSL certificate errors or HTTPS failures
• Solutions:
  • Verify certificate is valid and not expired
  • Check certificate chain and intermediate certificates
  • Ensure certificate matches hostname exactly
  • Verify certificate is installed in correct store

Log File Locations

• Installation Logs: Available via "Copy" button during installation
• IIS Logs: %SystemRoot%\System32\LogFiles\W3SVC1\
• Windows Event Logs: Applications and Services Logs
• SurePassID Logs: Application-specific log directories

Performance Optimization

Database Optimization

• Configure appropriate SQL Server memory settings
• Set up regular database maintenance plans
• Monitor database performance counters
• Implement proper backup strategies

IIS Optimization

• Configure appropriate application pool settings
• Enable output caching where appropriate
• Monitor IIS performance counters
• Configure compression for better performance

Network Optimization

• Configure appropriate timeout values
• Enable connection pooling for database connections
• Monitor network latency and throughput
• Implement load balancing for high availability

Security Considerations

Local Security Best Practices

• Service Accounts: Use dedicated service accounts with minimal privileges
• Database Security: Implement SQL Server security best practices
• Network Security: Configure firewalls and network segmentation
• Certificate Management: Implement proper certificate lifecycle management

Encryption and Key Management

• Data Encryption: Configure database encryption if required
• Key Storage: Secure encryption key storage and backup
• Key Rotation: Implement regular encryption key rotation
• Transport Security: Use HTTPS/TLS for all communications

Access Control

• Administrative Access: Limit administrative access to authorized personnel
• Service Permissions: Configure minimal required permissions for services
• Network Access: Restrict network access to required ports and protocols
• Audit Logging: Enable comprehensive audit logging and monitoring

Maintenance and Updates

Regular Maintenance Tasks

• System Updates: Keep Windows and components updated
• Certificate Renewal: Monitor and renew SSL certificates
• Database Maintenance: Regular backup and maintenance operations
• Log Rotation: Manage log file sizes and retention

Backup and Recovery

• Database Backups: Regular full and differential database backups
• Configuration Backups: Backup configuration files and settings
• Certificate Backups: Secure backup of SSL certificates and keys
• System Images: Regular system-level backups for disaster recovery

Monitoring and Alerting

• Service Monitoring: Monitor Windows services and IIS application pools
• Performance Monitoring: Track system performance metrics
• Security Monitoring: Monitor for security events and anomalies
• Capacity Planning: Monitor resource utilization and plan for growth

Important: Local installations provide maximum flexibility and control but require comprehensive system administration knowledge. Ensure proper planning, testing, and documentation before deploying to production environments. Regular maintenance and monitoring are essential for optimal system performance and security.