SurePassID Directory Sync Administrator Guide

SurePassID Authentication Server

SurePassID Directory Sync - Administrator Guide

Version: 2025.2
Last Updated: June 26, 2025

Administration Overview

Administrator Responsibilities

As a DirectorySync administrator, you are responsible for:

• Deploying and configuring DirectorySync
• Managing API keys and permissions
• Configuring synchronization sources and schedules
• Monitoring sync operations and troubleshooting issues
• Implementing security best practices
• Managing role-based access provisioning
• Maintaining logs and audit trails

System Architecture

[Active Directory] ----> [DirectorySync] ----> [SurePass MFA Server]
       |                      |                         |
   [LDAP Query]         [REST API]              [User Database]
   [Group Members]       [API Key]              [Token Management]

Installation and Deployment

System Requirements

Server Requirements:

• Windows Server 2016 or later
• .NET Framework 4.8
• 2 GB RAM minimum
• 500 MB disk space
• Network connectivity to:
  • Active Directory domain controller (port 389/636)
  • SurePass MFA Server (port 443)

Permissions Required:

• Read access to Active Directory
• Local administrator rights for installation
• API key with appropriate SurePass permissions

Installation Steps

1. Download Installation Package

   DirectorySync-2025.2-Setup.exe

2. Run Installer

   • Execute as Administrator
   • Accept license agreement
   • Choose installation directory (default: C:\Program Files\SurePassID\DirectorySync\)
   • Complete installation

3. Verify Installation

   cd "C:\Program Files\SurePassID\DirectorySync"
   .\DirectorySync.exe

4. Initial Configuration

   • Edit DirectorySync.exe.config
   • Add API credentials
   • Configure sync source
   • Test in preview mode

Deployment Scenarios

Single Server Deployment

Deploy on one server with scheduled task execution.

Pros:

• Simple to manage
• Lower resource requirements

Cons:

• Single point of failure
• No redundancy

Best For: Small to medium organizations (< 5,000 users)

Multiple Instance Deployment

Deploy multiple instances with different configurations.

Use Cases:

• Different token types for different user groups
• Different role assignments per department
• Separate AD groups with unique settings

Configuration:

1. Install DirectorySync once
2. Create multiple config files:
   • DirectorySync.exe.config (default)
   • DirectorySync-HelpDesk.exe.config
   • DirectorySync-Admins.exe.config
3. Create separate scheduled tasks pointing to different config files

Example PowerShell Script:

# Run for standard users
Start-Process "C:\Program Files\SurePassID\DirectorySync\DirectorySync.exe" -ArgumentList "-use_command_line false" -Wait

# Run for help desk
Start-Process "C:\Program Files\SurePassID\DirectorySync\DirectorySync.exe" -ArgumentList "-use_command_line true -config DirectorySync-HelpDesk.exe.config" -Wait

Execution Modes

DirectorySync supports two execution modes, each suited for different operational requirements.

Console Mode with Scheduled Task

Run DirectorySync as a console application triggered by Windows Task Scheduler.

Configuration:

<!-- Console mode with scheduled task - no special config needed -->
<add key="use_command_line" value="false" />
<add key="silent" value="true" />
<add key="mode" value="live" />

Creating a Scheduled Task (PowerShell):

# Daily sync at 2 AM
$action = New-ScheduledTaskAction -Execute "C:\Program Files\SurePassID\DirectorySync\DirectorySyncClientConsole.exe"
$trigger = New-ScheduledTaskTrigger -Daily -At 2:00AM
$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit (New-TimeSpan -Hours 1) -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 5)

Register-ScheduledTask -TaskName "SurePass DirectorySync" -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Description "Synchronize AD users with SurePassID"

Creating a Scheduled Task (Command Line):

schtasks /create /tn "SurePass DirectorySync" /tr "\"C:\Program Files\SurePassID\DirectorySync\DirectorySyncClientConsole.exe\"" /sc daily /st 02:00 /ru SYSTEM /rl HIGHEST

Advantages:

• Simple setup and management
• Low resource usage (runs only when scheduled)
• Easy to configure multiple instances with different schedules
• Clear execution history in Task Scheduler

Best For:

• Periodic synchronization (hourly to daily)
• Most organizations

Windows Service Mode

Run DirectorySync as a continuously running Windows Service.

Configuration:

<!-- Install as service: DirectorySyncClientConsole.exe install -->
<add key="sync_interval_minutes" value="60" />
<add key="silent" value="true" />
<add key="mode" value="live" />

AD Live Mode Service Configuration:

When using AD Live sync source, the service uses ad_live_poll_seconds instead of sync_interval_minutes:

<!-- Install as service: DirectorySyncClientConsole.exe install -->
<add key="sync_source" value="AdLive" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_live_poll_seconds" value="30" />  <!-- Polls every 30 seconds -->
<add key="silent" value="true" />
<add key="mode" value="live" />

Interval Behavior by Sync Source:

Service Installation:

# Install service (run as Administrator)
cd "C:\Program Files\SurePassID\DirectorySync"
DirectorySyncClientConsole.exe install

# Start service
DirectorySyncClientConsole.exe start

# Verify service is running
sc query SurePassDirectorySync

Service Management:

# Check status
Get-Service -Name "SurePassDirectorySync"

# Stop service
Stop-Service -Name "SurePassDirectorySync"

# Start service
Start-Service -Name "SurePassDirectorySync"

# Uninstall service
DirectorySyncClientConsole.exe stop
DirectorySyncClientConsole.exe uninstall

Service Features:

• Runs under Local System account
• Automatic startup with Windows
• Automatic recovery on failure:
  • First failure: Restart after 1 minute
  • Second failure: Restart after 5 minutes
  • Subsequent failures: Restart after 10 minutes
• Prevents overlapping sync operations

Advantages:

• Near real-time synchronization
• Automatic recovery from failures
• Continuous monitoring capability
• No dependency on user sessions

Best For:

• Frequent synchronization (every few minutes)
• Environments requiring near real-time updates
• Critical user provisioning workflows

Choosing the Right Mode

AD Live Sync Administration (New in 2025.2)

AD Live sync requires additional configuration and permissions compared to standard sync modes.

AD Permissions for DirSync

The service account needs "Replicating Directory Changes" permission:

# Grant DirSync permission (run as Domain Admin)
dsacls "DC=contoso,DC=com" /G "DOMAIN\ServiceAccount:CA;Replicating Directory Changes"

# Verify permission
dsacls "DC=contoso,DC=com" | Select-String "Replicating Directory Changes"

State File Management

AD Live maintains a state file (AdLiveState.json) containing:

• DirSync cookie (for incremental sync)
• Domain controller affinity
• Sync statistics

Best Practices:

• Back up state file regularly
• If state file is corrupted, delete it to force full sync
• Use absolute path for production deployments

<add key="ad_live_state_path" value="C:\ProgramData\SurePassID\DirectorySync\AdLiveState.json" />

AD Live Configuration Parameters

LDAP Credentials for AD Live

By default, AD Live sync uses the service account credentials (Negotiate/Kerberos) to connect to Active Directory. For environments where explicit credentials are required, you can configure LDAP bind credentials.

When to Use Explicit Credentials:

• Cross-domain scenarios where the service account doesn't have access
• Service running under LocalSystem and needs specific AD permissions
• Testing or debugging with a specific AD account
• Environments where Kerberos delegation is not configured

Configuration Example:

<add key="ad_live_ldap_username" value="DOMAIN\svc_dirsync" />
<add key="ad_live_ldap_password" value="SecurePassword123!" />

Credential Format:

• Down-level format: DOMAIN\username
• UPN format: username@domain.com

Security Notes:

• The LDAP password is automatically masked when displaying configuration parameters in logs
• Only the last 4 characters are shown (e.g., ****rd123!)
• Consider using a dedicated service account with minimum required permissions
• Store configuration files with restricted permissions (Administrators only)

Required AD Permissions for LDAP Account:

• Read access to user objects in monitored OUs
• "Replicating Directory Changes" permission on the domain (for DirSync control)

Monitoring AD Live Sync

Key Log Messages:

Directory Sync Service --Starting in AD Live mode. Poll interval: 30 seconds
Directory Sync --AD Live: Query returned 5 change(s)
Directory Sync --AD Live: User jdoe disabled successfully
Directory Sync --AD Live: Sync completed. Created=2, Disabled=1, Enabled=1, Deleted=0

State File Contents Example:

{
  "Cookie": "base64-encoded-dirsync-cookie",
  "DomainController": "dc01.contoso.com",
  "Domain": "contoso.com",
  "LastSyncTime": "2025-06-26T10:30:00Z",
  "LastChangeCount": 5,
  "TotalSyncCount": 1234,
  "TotalChangesProcessed": 5678
}

| Multiple sync configurations | Console + Scheduled Task | | Minimal server resource usage | Console + Scheduled Task | | Automatic failure recovery | Windows Service |

Post-Installation Verification

After installation, verify DirectorySync is working correctly using the included verification scripts.

Verification Scripts Location:

C:\Program Files\SurePassID\DirectorySync\Tools\Installation Verification Scripts\
    - README.txt                    # Detailed test documentation
    - RunVerificationTests.ps1      # Automated PowerShell verification
    - RunVerificationTests.bat      # Batch file wrapper

Running Verification:

cd "C:\Program Files\SurePassID\DirectorySync\Tools\Installation Verification Scripts"

.\RunVerificationTests.ps1 `
    -ApiKeyId "your-api-key-id" `
    -ApiKey "your-api-key" `
    -RestEndpoint "https://your-surepassid-server/api/mfa/v1"

Tests Performed:

1. Application help/usage verification
2. API connectivity test
3. XML sync preview test
4. Token configuration tests (OTP, FIDO2)
5. Error handling validation

Expected Results:

================================================================================
VERIFICATION SUMMARY
================================================================================
[PASS] Help Display
[PASS] Basic XML Preview
[PASS] Token Creation Preview
[PASS] FIDO2 Passkey Preview
[PASS] Invalid Credentials (expected failure)

Results: 5 passed, 0 failed
All verification tests passed! Installation is verified.

API Key Management

API Credential Parameter Naming

Important: As of version 2025.2, the command-line parameters for API credentials have been updated for clarity and consistency.

Backwards Compatibility:

• Legacy parameters (-ln, -lp) continue to work indefinitely
• Existing scripts and automation require no changes
• New deployments should use the recommended parameter names

Migration Notes:

• Config file settings have always used api_key_id and api_key (no change)
• Command-line parameter names now match config file naming for consistency
• See DirectorySyncTests\VerificationScripts\PARAMETER_NAME_MIGRATION.md for detailed migration guide

Creating API Keys

1. Log in to SurePass Admin Console
2. Navigate to Settings > API Keys
3. Click Create New API Key
4. Set permissions:
   • ? FindUser
   • ? AddUser
   • ? AddToken
5. Copy API Key ID and API Key (shown only once)
6. Store securely

Required Permissions

* Only if create_soft_token=true
** Reserved for future disable group functionality

Security Best Practices

1. Use Dedicated API Keys

   • Create separate keys for DirectorySync
   • Don't share keys across applications
   • Label keys clearly: "DirectorySync Production"

2. Rotate Keys Regularly

   • Rotate every 90 days
   • Maintain key rotation schedule
   • Update configuration after rotation

3. Secure Storage

   • Encrypt configuration files
   • Use Windows DPAPI for key storage
   • Restrict file permissions (Administrators only)

4. Audit API Usage

   • Review API logs regularly
   • Monitor for unusual activity
   • Alert on failed authentication attempts

Key Rotation Procedure

# 1. Create new API key in SurePass
# 2. Update configuration file
# 3. Test in preview mode
Set-Content -Path "DirectorySync.exe.config" -Value (Get-Content "DirectorySync.exe.config" -Raw).Replace("old-key-id", "new-key-id")

# 4. Run test
DirectorySync.exe -mode preview

# 5. Verify logs
Get-Content "Trace\*.log" -Tail 50

# 6. Disable old key in SurePass after verification

Configuration Management

Configuration File Management

Location: C:\Program Files\SurePassID\DirectorySync\DirectorySync.exe.config

Using External AppSettings File (configSource)

If you're using the configSource attribute in your main App.config to reference an external appSettings.config file, it's critical to use the correct format.

Main App.config (DirectorySync.exe.config):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Reference external appSettings file -->
  <appSettings configSource="appSettings.config" />
  
  <!-- Other configuration sections -->
</configuration>

External appSettings.config File:

⚠️ IMPORTANT: When using configSource, the external file must contain ONLY the section element (e.g., <appSettings>) without the XML declaration or <configuration> wrapper.

✅ CORRECT Format:

<appSettings>
  <add key="use_config_profiles" value="true" />
  <add key="profiles_list" value="XmlSync,AdGroupSync,AdminUsers" />
  <add key="use_command_line" value="false" />
  <add key="sync_interval_minutes" value="60" />
</appSettings>

❌ INCORRECT Format (Will Cause ConfigurationErrorsException):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="use_config_profiles" value="true" />
    <!-- This format will fail! -->
  </appSettings>
</configuration>

Common Error:

System.Configuration.ConfigurationErrorsException: The format of a configSource file 
must be an element containing the name of the section. (appSettings.config line 2)

Why This Matters:

• The configSource attribute expects only the inner content of the section
• The external file is merged into the main config at the point of reference
• Including <?xml?> declaration or <configuration> wrapper violates .NET configuration format rules

Migration from Full Config to configSource:

If you have an existing full configuration file and want to use configSource:

1. Create appSettings.config with only the <appSettings> section:

   <appSettings>
     <!-- Your settings here -->
   </appSettings>

2. Update main App.config to reference it:

   <appSettings configSource="appSettings.config" />

3. Test before deploying to production

Parameter Requirements by Sync Source

Use this quick reference to determine which parameters are needed for your sync source:

Parameter Validation

DirectorySync validates parameters based on the selected sync source:

AdGroup Mode:

• Requires: ad_domain_fqdn, ad_group
• Validates: API connection, AD connectivity, group existence

AdLdapFilter Mode:

• Requires: ad_domain_fqdn, ldap_filter
• Validates: API connection, AD connectivity, LDAP filter syntax

Xml Mode:

• Requires: xml_path
• Validates: API connection, file existence, XML format

AdLive Mode:

• Requires: ad_domain_fqdn
• Validates: API connection, AD connectivity, DirSync permissions
• Enforces: ad_live_poll_seconds >= 5 seconds

Best Practices:

1. Version Control

   # Backup before changes
   Copy-Item "DirectorySync.exe.config" "DirectorySync.exe.config.$(Get-Date -Format 'yyyyMMdd-HHmmss').bak"

2. Validation

3. • Always test in preview mode after changes
   • Verify logs before switching to live mode
   • Keep previous working configuration

4. Documentation

5. • Document all configuration changes
   • Maintain change log
   • Note who made changes and when

Environment-Specific Configurations

Maintain separate configurations for different environments:

DirectorySync.exe.config           # Production
DirectorySync.exe.config.dev       # Development
DirectorySync.exe.config.test      # Testing
DirectorySync.exe.config.backup    # Backup

Configuration Templates

Template 1: Standard Users

<!-- Standard employee provisioning -->
<add key="sync_source" value="AdGroup" />
<add key="ad_group" value="SurePass-Employees" />
<add key="sync_user_role" value="user" />
<add key="token_type" value="SurePassIDAuthenticatorMobile" />
<add key="token_usage_otp" value="true" />
<add key="token_usage_push" value="true" />

Template 2: Help Desk Staff

<!-- IT Help Desk provisioning -->
<add key="sync_source" value="AdGroup" />
<add key="ad_group" value="IT-HelpDesk" />
<add key="sync_user_role" value="helpdesk" />
<add key="sync_user_group" value="Help Desk" />
<add key="token_type" value="Fido" />
<add key="token_fido2_type" value="SecurityKey" />

Template 3: Administrators

<!-- IT Administrators provisioning -->
<add key="sync_source" value="AdGroup" />
<add key="ad_group" value="IT-Admins" />
<add key="sync_user_role" value="admin" />
<add key="sync_user_group" value="Administrators" />
<add key="token_type" value="Fido" />
<add key="token_fido2_type" value="SecurityKey" />

Role-Based Provisioning

Understanding User Roles

The sync_user_role parameter automatically assigns administrative roles during user provisioning.

Role Assignment Strategies

Strategy 1: AD Group Mapping

Map AD groups to SurePass roles:

AD Group                    ?  SurePass Role
--------------------------------  ------------------
"Domain Users"              ?  user
"IT-HelpDesk-T1"            ?  helpdesk
"IT-HelpDesk-Managers"      ?  helpdeskmgr
"IT-Admins"                 ?  admin
"IT-Security-Team"          ?  superadmin

Strategy 2: Multiple Sync Jobs

Run separate sync jobs for different roles:

Job 1: Standard Users

<add key="ad_group" value="SurePass-Users" />
<add key="sync_user_role" value="user" />

Job 2: Help Desk

<add key="ad_group" value="IT-HelpDesk" />
<add key="sync_user_role" value="helpdesk" />

Job 3: Administrators

<add key="ad_group" value="IT-Admins" />
<add key="sync_user_role" value="admin" />

Strategy 3: Departmental Roles

Assign roles based on department:

<!-- Marketing Department -->
<add key="ldap_filter" value="(&(objectClass=user)(department=Marketing))" />
<add key="sync_user_role" value="user" />

<!-- IT Department -->
<add key="ldap_filter" value="(&(objectClass=user)(department=IT))" />
<add key="sync_user_role" value="helpdesk" />

Role Security Considerations

1. Principle of Least Privilege

   • Assign minimum necessary role
   • Review role assignments regularly
   • Audit administrative access

2. Role Escalation Prevention

   • Don't automatically assign admin roles
   • Require manual approval for admin access
   • Monitor role changes

3. Compliance Requirements

   • Document role assignment policies
   • Maintain audit trail
   • Review access quarterly

Best Practices for Role Assignment

1. Default to User Role

   <add key="sync_user_role" value="user" />

2. Separate Sync Jobs for Admin Roles

   • Don't mix user and admin provisioning
   • Use different AD groups
   • Different schedules (admins less frequently)

3. Manual Override Process

   • Provision as user by default
   • Manually promote to admin roles as needed
   • Maintain approval workflow

4. Regular Access Reviews

   • Quarterly review of admin roles
   • Remove unused admin accounts
   • Validate role assignments match job functions

Security Considerations

Network Security

1. Secure Communication

   • Always use HTTPS for REST API calls
   • Enable TLS 1.2 or higher
   • Validate SSL certificates

2. Firewall Configuration

   Outbound Rules:
   - Allow TCP 443 to SurePass server
   - Allow TCP 389/636 to AD controllers
   
   Inbound Rules:
   - None required (DirectorySync is a client)

3. Network Segmentation

   • Deploy in secure management VLAN
   • Restrict access to server
   • Monitor network traffic

File System Security

# Secure configuration directory
$path = "C:\Program Files\SurePassID\DirectorySync"
$acl = Get-Acl $path
$acl.SetAccessRuleProtection($true, $false)
$adminRule = New-Object System.Security.AccessControl.FileSystemAccessRule("Administrators","FullControl","Allow")
$acl.SetAccessRule($adminRule)
Set-Acl $path $acl

Credential Security

1. Encrypt Configuration

   # Encrypt appSettings section
   aspnet_regiis -pef "appSettings" "C:\Program Files\SurePassID\DirectorySync"

2. Service Account Security

   • Use dedicated service account
   • Minimum AD read permissions
   • Rotate password regularly
   • No interactive logon rights

3. API Key Protection

   • Never commit keys to version control
   • Use environment variables for keys
   • Implement key rotation schedule

Audit and Compliance

1. Enable Comprehensive Logging

   <add key="silent" value="false" />

2. Log Retention

   • Retain logs for 90 days minimum
   • Archive to secure location
   • Compress old logs

3. Audit Trail

   • Track all user provisioning
   • Monitor role assignments
   • Alert on admin role provisioning

4. Compliance Reporting

   • Generate monthly provisioning reports
   • Document configuration changes
   • Maintain security incident logs

Monitoring and Maintenance

Log Monitoring

Log Location: C:\Program Files\SurePassID\DirectorySync\Trace\

Log File Format: SurePassDirectorySync<YYYYMMDD>.log

Key Log Patterns

Successful Sync:

Directory Sync --Endpoint OK.
Directory Sync --Active Directory search completed. There are X users in results set.
Directory Sync --User: username=jdoe was added.
Directory Sync --Token for username=jdoe was added.
Directory Sync --Final Stats: Users Read=X, Users Added=Y Tokens Added=Z Tokens Failed=0
Directory Sync --Finished: Successfully.

Failed Sync:

Directory Sync --Checking connection to endpoint FAILED. Error=...
Directory Sync --Username=jdoe was not added. Error=...
Directory Sync --Finished Errors: ...

Automated Log Monitoring

# PowerShell script to monitor for errors
$logPath = "C:\Program Files\SurePassID\DirectorySync\Trace"
$today = Get-Date -Format "yyyyMMdd"
$logFile = "$logPath\SurePassDirectorySync$today.log"

if (Test-Path $logFile) {
    $errors = Select-String -Path $logFile -Pattern "FAILED|Error|was not added"
    if ($errors) {
        # Send alert email
        Send-MailMessage -To "admin@contoso.com" `
            -From "directorysync@contoso.com" `
            -Subject "DirectorySync Errors Detected" `
            -Body "Errors found in sync: `n$($errors -join "`n")" `
            -SmtpServer "smtp.contoso.com"
    }
}

Performance Metrics

Monitor these metrics:

Health Check Script

# Daily health check
function Test-DirectorySyncHealth {
    $results = @{
        ConfigExists = Test-Path "C:\Program Files\SurePassID\DirectorySync\DirectorySync.exe.config"
        LogExists = Test-Path "C:\Program Files\SurePassID\DirectorySync\Trace\*.log"
        LastRun = (Get-ChildItem "C:\Program Files\SurePassID\DirectorySync\Trace\*.log" | 
                   Sort-Object LastWriteTime -Descending | 
                   Select-Object -First 1).LastWriteTime
        Errors = (Select-String -Path "C:\Program Files\SurePassID\DirectorySync\Trace\*.log" -Pattern "FAILED" -Context 0,2)
    }
    
    # Check if last run was within 24 hours
    if ((Get-Date) - $results.LastRun -gt (New-TimeSpan -Days 1)) {
        Write-Warning "DirectorySync has not run in over 24 hours!"
    }
    
    if ($results.Errors) {
        Write-Warning "Errors detected in recent sync!"
    }
    
    return $results
}

Maintenance Tasks

Daily

• Review sync logs for errors
• Verify scheduled task execution
• Check API connectivity

Weekly

• Review provisioned user count
• Verify AD group membership accuracy
• Check disk space in Trace folder

Monthly

• Archive old logs
• Review role assignments
• Update documentation
• Test disaster recovery procedure

Quarterly

• Rotate API keys
• Review and update configuration
• Conduct security audit
• Performance optimization review

Performance Optimization

Large User Populations (> 1,000 users)

1. Use AD Group Sync Instead of LDAP Filters

   • AD Group queries are more efficient
   • Better caching by AD
   • Reduced query complexity

2. Optimize Sync Frequency

   • Don't sync more than necessary
   • Consider business hours only
   • Stagger multiple sync jobs

3. Batch Processing

   • DirectorySync processes users sequentially
   • For very large groups (> 5,000), consider:
     • Multiple AD groups
     • Multiple sync instances
     • Load balancing across time

Network Optimization

1. Deploy Near AD Controllers

   • Minimize network latency
   • Prefer site-local DC

2. Bandwidth Considerations

   • Each user: ~5-10 KB transferred
   • 1,000 users ? 5-10 MB
   • Plan for API call overhead

Troubleshooting Performance Issues

Slow Sync Times:

1. Check AD connectivity and query performance

   Measure-Command { 
       Get-ADGroupMember -Identity "SurePass-Users" 
   }

2. Test API response times

   Measure-Command {
       Invoke-RestMethod -Uri "https://yourserver/api/mfa/v1/systemtime" -Headers @{Authorization="Bearer your-token"}
   }

3. Review antivirus exclusions

   • Exclude DirectorySync.exe
   • Exclude Trace folder from scanning

Disaster Recovery

Backup Procedures

1. Configuration Backup

   # Daily automated backup
   $date = Get-Date -Format "yyyyMMdd"
   $source = "C:\Program Files\SurePassID\DirectorySync\DirectorySync.exe.config"
   $dest = "\\backup-server\DirectorySync\Config-$date.config"
   Copy-Item $source $dest

2. Log Backup

   # Weekly log archive
   $source = "C:\Program Files\SurePassID\DirectorySync\Trace\*.log"
   $dest = "\\backup-server\DirectorySync\Logs\"
   Get-ChildItem $source -Recurse | 
       Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-7)} |
       Copy-Item -Destination $dest

Recovery Procedures

Scenario 1: Configuration File Corruption

1. Restore from backup:

   Copy-Item "\\backup-server\DirectorySync\Config-latest.config" "C:\Program Files\SurePassID\DirectorySync\DirectorySync.exe.config"

2. Test configuration:

   DirectorySync.exe -mode preview

Scenario 2: API Key Compromised

1. Disable compromised key in SurePass
2. Generate new API key
3. Update configuration
4. Test connectivity
5. Resume sync operations

Scenario 3: Server Failure

1. Install DirectorySync on new server
2. Restore configuration from backup
3. Verify AD connectivity
4. Test in preview mode
5. Update scheduled tasks
6. Resume operations

Business Continuity Planning

RTO (Recovery Time Objective): 4 hours
RPO (Recovery Point Objective): 24 hours

Minimum Recovery Requirements:

• DirectorySync configuration file
• Current API keys
• AD service account credentials
• Network access to AD and SurePass

Advanced Scenarios

Profile-Based Configuration (Recommended)

Use profiles to manage multiple sync configurations from a single service instance. Profiles are stored in %ProgramData%\SurePassID\DirectorySync\Profiles\ where no admin rights are required to edit them.

Enable Profiles in App.config:

<add key="use_config_profiles" value="true" />
<add key="profiles_list" value="AdminUsers,HelpdeskUsers,StandardUsers" />
<!-- Install as service: DirectorySyncClientConsole.exe install -->
<add key="sync_interval_minutes" value="60" />

Profile Path Resolution:

Setting Up Profiles:

# Create the profiles directory
$profilesDir = "$env:ProgramData\SurePassID\DirectorySync\Profiles"
New-Item -ItemType Directory -Path $profilesDir -Force

# Copy sample profiles from installation
Copy-Item "C:\Program Files\SurePassID\DirectorySync\Profiles\*.config" $profilesDir

Multi-Domain Synchronization

Sync users from multiple AD domains using profiles:

Profile: Domain1.config

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="domain1.com" />
<add key="ad_group" value="SurePass-Users" />
<add key="api_key_id" value="YOUR_KEY_ID" />
<add key="api_key" value="YOUR_KEY" />
<add key="rest_endpoint" value="https://yourserver/api/mfa/v1" />

Profile: Domain2.config

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="domain2.com" />
<add key="ad_group" value="SurePass-Users" />
<add key="api_key_id" value="YOUR_KEY_ID" />
<add key="api_key" value="YOUR_KEY" />
<add key="rest_endpoint" value="https://yourserver/api/mfa/v1" />

App.config:

<add key="use_config_profiles" value="true" />
<add key="profiles_list" value="Domain1,Domain2" />
<!-- Install as service: DirectorySyncClientConsole.exe install -->

Multi-Tenant Deployment

Sync to different SurePassID tenants from a single service:

Profile: TenantA.config

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_group" value="TenantA-Users" />
<add key="api_key_id" value="TENANT_A_KEY_ID" />
<add key="api_key" value="TENANT_A_KEY" />
<add key="rest_endpoint" value="https://tenant-a.surepassid.com/api/mfa/v1" />

Profile: TenantB.config

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_group" value="TenantB-Users" />
<add key="api_key_id" value="TENANT_B_KEY_ID" />
<add key="api_key" value="TENANT_B_KEY" />
<add key="rest_endpoint" value="https://tenant-b.surepassid.com/api/mfa/v1" />

Selective Token Types by Group

Provision different token types for different user groups using profiles:

Profile: Executives.config (Passkeys)

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_group" value="Executives" />
<add key="token_type" value="Fido" />
<add key="token_fido2_type" value="Passkey" />
<add key="api_key_id" value="YOUR_KEY_ID" />
<add key="api_key" value="YOUR_KEY" />
<add key="rest_endpoint" value="https://yourserver/api/mfa/v1" />

Profile: Employees.config (Push + OTP)

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_group" value="Employees" />
<add key="token_type" value="SurePassIDAuthenticatorMobile" />
<add key="token_usage_otp" value="true" />
<add key="token_usage_push" value="true" />
<add key="api_key_id" value="YOUR_KEY_ID" />
<add key="api_key" value="YOUR_KEY" />
<add key="rest_endpoint" value="https://yourserver/api/mfa/v1" />

App.config:

<add key="use_config_profiles" value="true" />
<add key="profiles_list" value="Executives,Employees" />

Graduated Rollout Strategy

Phase-in MFA deployment:

Phase 1: Pilot Group (Week 1-2)

<add key="ad_group" value="MFA-Pilot-Group" />
<add key="mode" value="live" />

Phase 2: IT Department (Week 3-4)

<add key="ad_group" value="IT-Department" />
<add key="mode" value="live" />

Phase 3: All Users (Week 5+)

<add key="ad_group" value="All-Employees" />
<add key="mode" value="live" />

Integration with ITSM Tools

Log to ServiceNow or other ITSM tools:

# Parse logs and create incidents for failures
$errors = Select-String -Path $logFile -Pattern "FAILED|Error"
foreach ($error in $errors) {
    # Call ServiceNow API to create incident
    $body = @{
        short_description = "DirectorySync Error"
        description = $error.Line
        category = "IT Services"
        urgency = 3
    } | ConvertTo-Json
    
    Invoke-RestMethod -Uri "https://yourinstance.service-now.com/api/now/table/incident" `
        -Method Post -Body $body -ContentType "application/json" `
        -Headers @{Authorization="Basic $encodedCreds"}
}

Support and Escalation

Level 1: Check Logs

• Review Trace logs
• Verify configuration
• Test API connectivity

Level 2: SurePass Support

• Email: support@surepassid.com
• Include: Logs, configuration (redact API keys), error messages

Level 3: Emergency Support

• Critical issues affecting production
• Response time: 4 hours
• 24/7 emergency hotline

Appendix

A. Configuration Parameter Reference

See User Guide for complete parameter list.

B. API Error Codes

The software and information contained herein are proprietary to, and comprise valuable trade secrets of, SurePassID Authentication, Inc., which intends to preserve as confidential trade secrets such software and information.

For Support