SurePassID Authentication Server

Azure MFA-As-Code Installer

Overview

The AdminCustomInstall application is a Windows Forms-based installation wizard for SurePassID authentication systems. When deployed in Azure environments, the application automatically detects the Azure platform and enables specialized configuration features for Azure Virtual Lab Environment (VLE) and Azure Marketplace deployments.

Azure Environment Detection

The application automatically detects Azure environments by:

• Querying the Azure Instance Metadata Service (IMDS) at http://169.254.169.254/metadata/instance
• Analyzing the response to determine if running in Azure or Azure Marketplace
• Configuring appropriate installation flows based on the detected environment

Environment Types

1. Azure Environment (InstallEnvironment.Azure)

Standard Azure deployment with full administrative control over infrastructure resources.

2. Azure Marketplace Environment (InstallEnvironment.AzureMarketPlace)

Azure Marketplace deployment with additional marketplace-specific configurations and constraints.

Azure Installation Flow

Initial Setup and Detection

When launching the application in Azure:

1. Azure Environment Check:

   Checking Azure availability for Azure cloud endpoint...

   • The application queries Azure IMDS to confirm Azure environment
   • Displays detected environment type in the log

2. VLE Status Assessment:

   Azure VLE Install Status=[Status]

   • Checks Azure Private Cloud Operations (PCO) installation status
   • Determines initialization requirements

Azure VLE Installation Stages

The Azure installation process has multiple stages depending on the current system state:

Stage 1: VLE Initialization (If Required)

If the system detects uninitialized VLE components, you'll see:

System configuration files needs to be initialized. Please press the Initialize button to start initialization and then review the log when it has completed.

Button Changes: The main button will display "Initialize" instead of "Start"

Required Information:

• Azure Subscription ID
• Organization identifier (short name for your company)
• Azure region selection
• Infrastructure build type (Full or Express)
• Azure administrator details (optional but recommended)

Stage 2: Full System Configuration

After VLE initialization or if the system is already initialized:

Standard Installation Wizard Steps:

1. Installation Wizard - Main installation page
2. Customize Account - Account and service configuration
3. Define Users - User account setup
4. Create Database - Database configuration with Azure SQL support
5. SMS & Voice Notifications - Twilio configuration for notifications
6. Set Email Notifications - SMTP configuration
7. Specify License File - License configuration

Note: The "SurePassID Services" (DNS) and "Setup Key Vault" steps are automatically skipped in Azure VLE environments as these are pre-configured.

Azure VLE Initialization Wizard

Private Cloud Options Configuration

When initialization is required, you'll encounter the VLE Options wizard:

Organization Settings

• Organization Identifier: Short abbreviation for your company (alphanumeric only, max 15 characters)
• Azure Subscription: Your Azure subscription ID
• Common Region: Primary Azure region for SQL database and key vaults

Infrastructure Flow Type

• Full: Complete infrastructure deployment with all components
• Express: Streamlined deployment for faster setup

Azure Administrator Whitelist (Optional)

Configure up to 2 Azure administrators for enhanced security:

Administrator 1:

• Display Name: Human-readable name for the administrator
• Entra ID GUID: Valid Azure AD object ID for the administrator
• Client IP: Valid IPv4 address for IP-based access control

Administrator 2 (Optional):

• Same fields as Administrator 1
• Leave Display Name empty to skip this administrator

Validation Requirements

• Organization identifier must be alphanumeric characters only
• Entra ID GUIDs must be valid GUID format
• Client IPs must be valid IPv4 addresses
• All required fields must be populated before proceeding

Azure Configuration Files

The VLE initialization process manages several Azure-specific configuration files:

JSON Configuration Files

• mfa-admin-data.jsonc: Administrator whitelist and access control
• mfa-common-region-data.jsonc: Region and SQL administrator settings
• mfa-prod-sql-admin-password.json: SQL administrator credentials
• kv-secrets-mfa-params.json: MFA Key Vault secrets
• kv-secrets-api-params.json: API Key Vault secrets

Shell Scripts

• mfa-run-prod-config.sh: Main deployment script
• mfa-delete-surepassid-resources.sh: Resource cleanup script
• app-service/: App Service deployment scripts
• key-vault/: Key Vault management scripts

Azure-Specific Features

Automatic Key Vault Integration

• Generates cryptographically secure encryption keys
• Configures Azure Key Vault secrets automatically
• Sets up proper key rotation policies

Azure SQL Database Configuration

• Generates secure SQL administrator credentials
• Creates dedicated database users with minimal required permissions
• Configures private link endpoints for secure connectivity

Infrastructure as Code (IaC) Support

• Updates Bicep parameter files with configuration values
• Generates deployment-ready infrastructure scripts
• Supports both government and commercial Azure clouds

User Interface Features in Azure Mode

Enhanced Logging

Real-time progress display with detailed Azure-specific operations:

• Azure environment detection results
• VLE initialization progress
• Configuration file updates
• Infrastructure deployment status

Copy to Clipboard

• Copy Button: Available to copy all log output to clipboard for troubleshooting
• Useful for sharing configuration details with support teams

Step Progress Indicators

Window titles show progress: "Step X of Y - [Step Name]"

Common Azure Deployment Scenarios

New Azure VLE Deployment

1. Launch AdminCustomInstall on Azure VM
2. Application detects Azure environment
3. VLE initialization wizard appears
4. Complete VLE configuration
5. System proceeds to standard installation wizard
6. Configure remaining components (database, notifications, etc.)

Existing Azure Infrastructure

1. Application detects initialized VLE environment
2. Skips VLE initialization
3. Proceeds directly to standard installation steps
4. Uses pre-configured Azure resources

Azure Marketplace Deployment

1. Application detects Azure Marketplace environment
2. Uses marketplace-specific configuration templates
3. Limited customization options due to marketplace constraints
4. Automated resource provisioning

Prerequisites for Azure Installation

Azure Resources

• Azure subscription with appropriate permissions
• Resource group for SurePassID deployment
• Azure SQL Database (or creation permissions)
• Azure Key Vault (or creation permissions)
• Virtual network and subnet configuration

Permissions Required

• Contributor role on target resource group
• Key Vault Administrator on target Key Vault
• SQL DB Contributor for database operations
• Application Administrator for Entra ID integration (if configuring admin whitelist)

Network Requirements

• Outbound internet connectivity for Azure API calls
• Access to Azure Instance Metadata Service (IMDS)
• Connectivity to target Azure SQL Database
• Access to Azure Key Vault endpoints

Troubleshooting Azure Issues

Environment Detection Problems

Issue: Application doesn't detect Azure environment Solution:

• Verify IMDS accessibility: curl -H "Metadata:true" "http://169.254.169.254/metadata/instance?api-version=2021-02-01"
• Check VM configuration allows IMDS access
• Ensure no network restrictions blocking metadata service

VLE Initialization Failures

Issue: VLE initialization fails Solutions:

• Verify Azure subscription ID is correct
• Check permissions on target resource group
• Ensure Azure CLI or PowerShell connectivity
• Review configuration file paths and accessibility

Configuration File Errors

Issue: JSON configuration files not found or invalid Solutions:

• Verify folder structure matches expected Azure VLE layout
• Check file permissions for configuration directories
• Validate JSON syntax in configuration files
• Ensure all required placeholder values are populated

Key Vault Access Issues

Issue: Cannot access or configure Azure Key Vault Solutions:

• Verify Key Vault access policies
• Check managed identity configuration
• Ensure proper RBAC roles assigned
• Validate Key Vault network access rules

Security Considerations

Credential Management

• SQL passwords are automatically generated with 30+ character complexity
• Key Vault secrets use cryptographically secure random generation
• Administrative credentials are never logged or displayed in plain text

Network Security

• Private endpoints are configured for Azure SQL Database
• Key Vault access uses private networking where possible
• Administrative IP whitelisting provides additional access control

Access Control

• Entra ID integration for administrator authentication
• Role-based access control (RBAC) for Azure resources
• Principle of least privilege for service accounts

Post-Installation Verification

Azure Resource Verification

1. Resource Group: Confirm all expected resources are deployed
2. Key Vault: Verify secrets are properly configured
3. SQL Database: Test connectivity and permissions
4. App Services: Confirm deployment and configuration

Connectivity Tests

1. Database: Test application database connectivity
2. Key Vault: Verify secret retrieval functionality
3. External Services: Test SMTP and SMS integrations
4. Authentication: Verify user authentication workflows

Monitoring Setup

1. Azure Monitor: Configure application insights and logging
2. Alerts: Set up monitoring alerts for critical components
3. Backup: Verify database and key vault backup policies
4. Security: Review security center recommendations

Support and Maintenance

Log Collection

Use the "Copy" button to capture installation logs for troubleshooting. Include:

• Full installation log output
• Azure environment detection results
• Any error messages or warnings
• Configuration file contents (sanitize sensitive data)

Regular Maintenance

• Key Rotation: Plan regular encryption key rotation
• Certificate Renewal: Monitor and renew SSL/TLS certificates
• Security Updates: Keep Azure resources and applications updated
• Backup Verification: Regularly test backup and restore procedures

Important: Azure VLE deployments require careful planning and proper Azure permissions. Always test the installation process in a development environment before deploying to production. Ensure you have proper backup and rollback procedures in place.