SurePassID Directory Sync Release Notes

SurePass Directory Sync - Release Notes

Release: Version 2025.2
Release Date: June 26, 2025

Version 2025.2 - June 26, 2025

What's New

Profile-Based Configuration (NEW)

DirectorySync now supports multiple configuration profiles, enabling complex deployment scenarios from a single installation.

Features:

• Run multiple sync configurations from a single service instance
• Each profile can sync different AD groups, use different token types, or target different SurePassID tenants
• Profiles stored in %ProgramData%\SurePassID\DirectorySync\Profiles\ (no admin rights required to edit)
• Supports role-based provisioning (Admins, Helpdesk, Users with different settings)
• Multi-tenant deployments with different API endpoints per profile

New Parameters (App.config only):

• use_config_profiles - Enable profile-based configuration (true/false)
• profiles_list - Comma-separated list of profile names or paths

Profile Resolution: | Input | Resolved Path | |-------|---------------| | AdGroupSync | %ProgramData%\SurePassID\DirectorySync\Profiles\AdGroupSync.config | | C:\Config\Custom.config | C:\Config\Custom.config |

Configuration Example (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" />

Sample Profiles Included:

• XmlSync.config - XML file sync
• AdGroupSync.config - AD Group sync
• AdLiveSync.config - Real-time AD monitoring
• AdLdapFilterSync.config - Custom LDAP filter sync
• Fido2Passkey.config - FIDO2 Passkey tokens
• Fido2SecurityKey.config - FIDO2 Security Key tokens
• AdminUsers.config - Admin role users
• HelpdeskUsers.config - Helpdesk role users
• MultiTenant-TenantA.config / MultiTenant-TenantB.config - Multi-tenant examples

Use Cases:

• Sync different AD groups with different token types
• Provision admins with one profile, users with another
• Multi-tenant deployments syncing to different SurePassID servers
• Separate configurations for different departments

DirectorySyncRunner - Testable Sync Engine (NEW)

The sync execution logic has been refactored into a separate, testable component.

Benefits:

• Improved testability with structured results
• Better error handling and reporting
• Reusable sync logic across console, service, and test modes

New Classes:

• DirectorySyncRunner - Core sync execution logic
• SyncResult - Structured result with success/failure, timing, and statistics

SyncResult Properties:

public class SyncResult
{
    public string ProfileName { get; set; }
    public bool Success { get; set; }
    public bool Skipped { get; set; }
    public string ErrorMessage { get; set; }
    public string SyncSource { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime EndTime { get; set; }
    public TimeSpan Duration { get; }
}

AD Live Sync Mode (NEW)

DirectorySync now supports real-time Active Directory change monitoring using the LDAP DirSync control.

New Sync Source: AdLive

Features:

• Near real-time detection of AD user changes
• Processes user creates, deletes, enables, and disables
• Configurable action when users are deleted from AD (Disable, Delete, or None)
• State persistence across service restarts
• OU-based filtering
• Efficient incremental sync (only changed objects)
• Optional explicit LDAP credentials for cross-domain or special authentication scenarios

New Parameters:

• ad_live_poll_seconds - Polling interval (default: 30 seconds)
• ad_live_state_path - Path to state file (default: AdLiveState.json)
• ad_live_deleted_user_action - Action on AD delete: Disable, Delete, None
• ad_live_monitor_ous - OUs to monitor (* = all)
• ad_live_user_filter - LDAP filter for users
• ad_live_process_disables - Process disable events (true/false)
• ad_live_process_deletes - Process delete events (true/false)
• ad_live_process_enables - Process enable events (true/false)
• ad_live_ldap_username - Optional LDAP bind username (format: DOMAIN\user or user@domain.com)
• ad_live_ldap_password - Optional LDAP bind password (automatically masked in logs)

Configuration Example:

<add key="sync_source" value="AdLive" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_live_poll_seconds" value="30" />
<add key="ad_live_deleted_user_action" value="Disable" />
<!-- Optional: Explicit LDAP credentials -->
<add key="ad_live_ldap_username" value="DOMAIN\svc_dirsync" />
<add key="ad_live_ldap_password" value="YourSecurePassword" />
<!-- Install as service: DirectorySyncClientConsole.exe install -->

LDAP Credentials:

• By default, uses the Windows service account credentials (Negotiate/Kerberos)
• Optional explicit credentials for cross-domain or special scenarios
• Password is automatically masked in logs (shows only last 4 characters)
• Supports both down-level (DOMAIN\user) and UPN (user@domain.com) formats

Requirements:

• Service account needs "Replicating Directory Changes" AD permission
• Recommended to run as Windows Service for continuous monitoring

Note: The ad_live_monitor_groups parameter is defined but not yet implemented.

User Role Assignment During Synchronization

DirectorySync now supports automatic user role assignment during the provisioning process, eliminating the need for manual role configuration after user creation.

New Parameter: sync_user_role

Supported Roles:

• user - Standard end user (default)
• helpdesk - Help desk support personnel
• helpdeskmgr - Help desk manager
• admin - Administrator
• superadmin - Super administrator

Benefits:

• Automated role provisioning reduces administrative overhead
• Ensures users have correct access from day one
• Supports role-based access control policies
• Enables differentiated provisioning for different AD groups

Configuration Example:

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

Use Cases:

• Provision IT help desk staff with appropriate administrative access
• Automatically grant admin roles to IT administrators
• Separate user provisioning from administrator provisioning

Windows Service Mode Support

DirectorySync can now run as a Windows Service for continuous, automated synchronization.

New Parameters:

• sync_interval_minutes - Interval between sync operations (default: 60)

Note: The application automatically detects if running as a Windows Service using Environment.UserInteractive. No configuration setting is required.

Service Installation:

DirectorySyncClientConsole.exe install
DirectorySyncClientConsole.exe start

Service Features:

• Automatic startup with Windows
• Automatic recovery on failure
• Configurable sync interval
• Prevents overlapping sync operations

Configuration Example:

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

Use Cases:

• Near real-time user provisioning
• Continuous monitoring environments
• Organizations requiring frequent synchronization

Installation Verification Scripts

New verification scripts are included to help validate installations.

Location: Tools\Installation Verification Scripts\

Files Included:

• README.txt - Comprehensive test documentation
• RunVerificationTests.ps1 - Automated PowerShell verification script
• RunVerificationTests.bat - Batch file launcher

Usage:

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

Tests Include:

• API connectivity verification
• XML sync preview testing
• Token configuration validation (OTP, FIDO2)
• Error handling verification

Security Enhancement: Password Masking in Logs

Sensitive configuration parameters are now automatically masked when displayed in logs and console output.

Masked Parameters:

• api_key_id - Shows last 4 characters only
• api_key - Shows last 4 characters only
• ad_live_ldap_password - Shows last 4 characters only

Example Log Output:

Directory Sync --Options:
  api_key_id=************abcd
  api_key=************1234
  ad_live_ldap_username=DOMAIN\svc_dirsync
  ad_live_ldap_password=********ord!

This ensures that sensitive credentials are not exposed in log files or console output during troubleshooting.

Version 2025.1 - June 17, 2025

Bug Fixes and Improvements

DIRSYNCLVE-28 & DIRSYNCLVE-33

• Fixed configuration parsing edge cases for FIDO2 token types
• Improved LDAP synchronization reliability
• Enhanced validation logic for token parameters
• Better error handling in configuration validation

Impact: More stable FIDO2 token provisioning with clearer error messages

Version 2025.0 - June 10, 2025

Major New Features

FIDO2 Passwordless Authentication Support (DIRSYNCLVE-27 & DIRSYNCLVE-28)

DirectorySync now supports modern FIDO2 authentication, including Passkeys and Security Keys.

New Token Types:

1. Passkey (FIDO2_UV)

   • Platform authenticators with user verification
   • Windows Hello, Face ID, Touch ID support
   • Passwordless authentication
   • Configuration: token_fido2_type="Passkey"

2. Security Key (FIDO2_2FA)

   • External hardware authenticators
   • YubiKey, Titan Key, etc.
   • Phishing-resistant 2FA
   • Configuration: token_fido2_type="SecurityKey"

New Parameters:

• token_fido2_type - Select Passkey or SecurityKey
• token_usage_push_type - Select Push or Fido2 push notifications

Configuration Example:

<add key="token_type" value="Fido" />
<add key="token_fido2_type" value="Passkey" />

Enhanced Token Usage Configuration

New Token Usage Options:

• token_usage_otp - Enable/disable OTP codes
• token_usage_push - Enable/disable push notifications
• token_usage_push_type - Standard Push or FIDO2 Push

Flexible Combinations:

• OTP only
• Push only
• OTP + Standard Push
• OTP + FIDO2 Push
• Push + FIDO2

Benefits:

• Users can choose their preferred authentication method
• Backup methods available if primary fails
• Future-proof for new authentication types

Improved Configuration Validation

• Enhanced validation for time-based OTP parameters
• Enhanced validation for event-based OTP parameters
• FIDO2 tokens bypass OTP validation appropriately
• Clear, actionable error messages with valid range guidance

Error Message Examples:

TokenOtpDriftUnit=10 is invalid. The value cannot be less than zero and is usually between one and three.
TokenOtpWindow=5 is invalid. The value cannot be less than one and is usually greater than or equal to thirty.

User-Friendly Display Names

• Preview mode shows human-readable token type names
• "Passkey" instead of "FIDO2_UV"
• "SecurityKey" instead of "FIDO2_2FA"
• Clearer log messages for troubleshooting

Bug Fixes

• Fixed OTP parameter validation for edge cases (June 11, 2025)
• Improved handling of malformed configuration values
• Better error recovery in token provisioning

Version 2024.5 - May 22, 2025

Major New Features

Active Directory Group-Based Synchronization

New synchronization source that monitors AD group membership for automated user provisioning.

New Sync Source: AdGroup

Key Features:

• Direct integration with AD group membership
• Automatic user provisioning when added to designated group
• Extracts user profile from AD (name, email, mobile, etc.)
• Support for nested group filtering
• Enhanced logging and error messages

New Parameters:

• ad_group - AD group to monitor for user additions
• ad_disable_group - AD group for future user de-provisioning support

Configuration Example:

<add key="sync_source" value="AdGroup" />
<add key="ad_domain_fqdn" value="contoso.com" />
<add key="ad_group" value="SurePass-MFA-Users" />

Benefits:

• Zero-touch user provisioning
• Leverage existing AD group management
• Faster onboarding for new employees
• Reduced IT administrative burden
• Eliminates manual data entry errors

Technical Implementation:

• Uses System.DirectoryServices.AccountManagement
• PrincipalContext and GroupPrincipal for robust AD integration
• Filters to process only UserPrincipal objects
• Detailed trace logging for troubleshooting

Improvements

• Enhanced LDAP query performance
• Better error handling in AD connectivity
• Improved log formatting and readability

Version 2024.4 - May 13, 2025

Enhancements

• Updated SurePassClientLibRest submodule
• Improved REST API error handling
• Enhanced connection retry logic

Upgrade Instructions

Upgrading from 2025.1 to 2025.2

Steps:

1. Backup Current Configuration

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

2. Stop Scheduled Tasks

   Disable-ScheduledTask -TaskName "DirectorySync"

3. Run Installer

   • Execute DirectorySync-2025.2-Setup.exe as Administrator
   • Existing configuration will be preserved

4. Review Configuration

   • Optionally add sync_user_role parameter
   • Test in preview mode

5. Test in Preview Mode

   cd "C:\Program Files\SurePassID\DirectorySync"
   .\DirectorySync.exe -mode preview

6. Review Logs

   • Check Trace\ folder for any errors
   • Verify user provisioning would work as expected

7. Enable Scheduled Tasks

   Enable-ScheduledTask -TaskName "DirectorySync"

Configuration Changes:

Optional new parameter:

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

Backward Compatibility: Fully backward compatible. Existing configurations work without modification. The sync_user_role parameter defaults to no role assignment if not specified.

Upgrading from 2025.0 to 2025.2

Follow same steps as 2025.1 to 2025.2. No breaking changes.

Upgrading from 2024.x to 2025.2

Important: Review all new features and parameters.

Steps:

1. Backup configuration (see above)
2. Review new parameters:
   • token_fido2_type (if using FIDO2)
   • token_usage_push_type (if using push)
   • sync_user_role (if assigning roles)
3. Run installer
4. Test extensively in preview mode
5. Gradually roll out to production

New Features Available:

• FIDO2 Passkey and Security Key support
• Enhanced token usage configuration
• Improved validation
• User role assignment

Known Issues

Version 2025.2

Issue: Disable group functionality not yet implemented
Workaround: Manually disable users in SurePass or use AD Live mode with ad_live_deleted_user_action=Disable
Status: Planned for future release

Issue: Role assignment only works during initial provisioning
Workaround: Manually change user roles in SurePass admin console for existing users
Status: By design - role assignment is provisioning-time only

Issue: AD Live ad_live_monitor_groups parameter not implemented
Workaround: Use ad_live_monitor_ous for OU-based filtering, or use AD Group sync mode for group-based provisioning
Status: Planned for future release

Deprecation Notices

run_as_service Configuration Setting (Deprecated)

The run_as_service configuration setting is no longer required and has been deprecated.

Previous Behavior:

<add key="run_as_service" value="true" />  <!-- Required to run as service -->

New Behavior:

• The application automatically detects if running as a Windows Service using Environment.UserInteractive
• No configuration setting is needed
• To install as a service, use: DirectorySyncClientConsole.exe install

Migration: Simply remove the run_as_service setting from your configuration. Existing configurations with this setting will continue to work (the setting is ignored).

System Requirements

Version 2025.2

Operating System:

• Windows Server 2016 or later
• Windows 10/11 (for testing)

Framework:

• .NET Framework 4.8

SurePass Server:

• Version 2024.1 or later for FIDO2 support
• Version 2023.1 or later for basic functionality

Active Directory:

• Windows Server 2012 R2 or later domain functional level
• Read access to AD required

Getting Help

Documentation

• User Guide: USER_GUIDE.md
• Administrator Guide: ADMINISTRATOR_GUIDE.md
• Online Docs: https://docs.surepassid.com

Support

• Email: support@surepassid.com
• Phone: 1-888-SUREPASS
• Portal: https://support.surepassid.com

Reporting Issues

When reporting issues, please include:

1. DirectorySync version
2. SurePass server version
3. Configuration file (redact API keys)
4. Relevant log entries from Trace\ folder
5. Steps to reproduce
6. Expected vs. actual behavior

Version History Summary

Roadmap

Planned for Future Releases

• AD Live Group Filtering: Implement ad_live_monitor_groups for group-based filtering in AD Live mode
• Disable Group Implementation: Automatic user disabling when moved to designated AD group
• Role Update Support: Update existing user roles during synchronization
• Multi-Domain Support: Single configuration for multiple AD domains
• Web-Based Configuration: GUI for configuration management
• Event-Driven Sync: True real-time synchronization using AD change notifications (beyond polling)
• Group Assignment: Automatically assign users to SurePass groups based on AD group membership
• Custom Field Mapping: Map custom AD attributes to SurePass fields

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.