Preface

This guide is intended for ADSync Users and Groups. It provides comprehensive details on how to use Active Directory Synchronization utility and its wide array of rich features. It will help you carry out necessary installations, configurations and troubleshooting as required. Please carefully follow this guide to get yourself acquainted with the ADSync Tool.

©2024. All rights reserved.


Tool for Directory Synchronization

Tool for Directory Synchronization consolidates one Active Directory with another. It performs one-way synchronization and keeps your cloud "User accounts" and "Groups" updated.

Tool for Directory Synchronization comes with artificial intelligence to automatically map the hosted and on-premises users on the basis of known attributes (user principal name, display name). It allows on-premise active directory admin to automatically sync newly created local or on-premise active directory users to sync with hosted active directory. Hence, it reduced the time, efforts and keeps your active directory sync all the time.

Description

ADSync is a utility consisting of multiple components used to synchronize local active directory objects with Hosted/Cloud Active Directory objects.

Types of object(s) which are currently synchronized.

  1. User Accounts

  2. Groups

The data fields which are being synchronized through this utility for User Accounts are:

Address, BusinessPhone, City, Company, Country, Department, Description, DirectManager, DisplayName, Fax, Email, FirstName, HomePhone, Initials, JobTitle, LastName, MobilePhone, Notes, OfficeLocation, Pager, proxyAddresses‘[EUM addresses Only]’, sAMAccountName, State, UserPrincipalName, wwwHomePage, ZipCode.

The data fields which are being synchronized through this utility for Groups are:

  1. Name
  2. Display Name
  3. Type
  4. Members

Configuration

The Active directory sync configuration is divided in two parts.

  1. Control Panel Configuration
  2. ADSync Configuration


ADSync Installation

Active Directory Synchronization - Installation

ADSync Installation Types

There are two different installations:

  1. Primary Domain Controller
  2. Additional Domain Controller.

This installer contains both the utilities and asks you for installation type during setup.

Note:You must install ADSync tool on your Primary Domain Controller and on all of the Additional Domain Controllers. 1st install ADSync and configure it on Primary Domain Controller and follow instructions below for Additional Domain Controller(s)

Installation of Active Directory Sync Utility

  • Install .Net Framework 3.5 features as shown below:

  • This utility requires Microsoft Visual C++ 2010 x64 to work, it is installed if not already present on the server. Please click Install button to start download and installation of Microsoft Visual C++ 2010 on this machine.

  • After pre-requisite verification and installation, installer will start setup for AD Sync utility. ClickNext to start the setup.

  • Select Installation type.

  • Select installation folder.

  • Review Settings. Click Next to Install.

  • After installation finish a screen will appears and ADSync Configuration Studio will open; if installation is for Primary Domain Controller.

Reboot Required

Yes: You must Reboot ALL Domain Controllers (Primary and Additional) where ADSync tool is installed.


Reboot

Reboot Required

Yes: You must Reboot ALL Domain Controllers (Primary and Additional) where ADSync tool is installed.


Enable/Disable ADSync

To enable/disable ADSync for an organization navigate to the following path:

Navigation: Home » Service Director » Active Directory » Organizations

Now select the organization for which you want to Enable/Disable ADSync and click Enable/Disable ADSync.

In Active Directory Organizations if you Enable ADSync on any organization, a pop-up shown will appear to select ADSync Template.

  • Apply To: Select Organization to which you want to apply the Template.

Click on Save button when done.


ADSync Templates

Add ADSync Template

To add a new ADSync template navigate to the following path:

Navigation: Home » Service Director » Active Directory » ADSync Templates

With each listed Template there are options for Set as default, Edit and Remove.

To add a new template click on Add ADSync Template button. It displays the following listing:

  1. Template Name: Enter Template name.
  2. Description: Enter description.
  3. Set As Default Template: Select this option to set it default.
  4. Select attribute to Sync: There are following attributes that can be synced, Description, Display name, First Name, Last Name, Email, Initials, Middle Name, UPN, Direct Manager, Home phone, Mobile phone, Business phone, Pager Home, Page Fax, Address City, Country, State, Zip code, Company, Job title, Department, Office Location, Password, Notes, Proxy, Addresses
  5. Apply To: Select Organization to which you want to apply the Template.

Click on Save button when done.


ADSync Usage Report

AdSync Usage report delivers to provider valuable information about Organizations and users that are synced using Adsync.

To view ADSync Usage Report, navigate to the following path:

Navigation: Home » Service Director » Active Directory » ADSync Usage Report

Under AdSync Organization Report tab, You can Export to Excel the organization Usage Report. It displays the following listing:

  1. Company Name: It shows the name of company.
  2. Organization Name: It shows the name of organization.
  3. Customer Name: It shows the customer name with id.
  4. Owner: It shows the owner name.
  5. Users synchronized: It shows the total number of users synchronized.
  6. Users not synchronized: It shows the number of users not synchronized.
  7. Total Users: It shows total number of user in an organization.

Under Users Synchronized tab, You can Export to Excel the user sync report. It displays following listing:

  1. Company Name: It shows the name of company.
  2. Organization Name: It shows the name of organization.
  3. Customer Name: It shows the customer name with id.
  4. Owner: It shows the owner name.
  5. User Display Name: It shows the user display name.
  6. User Principal Name: It shows UPN.
  7. Last Synced: It shows last synced date/time.


ADSync Configuration

Active Directory Synchronization - Configuration

When installation finishes on Primary Domain Controller, ADSync Configuration Studio will appear. When you click on configuration studio you will see Home screen.

Click Settings to configure local Active Directory settings, destination Control Panel, sync interval and logging.

Click Profiles to configure and manage what to synchronize between a source OU and a target OU.

Terminology used:

Terms used to reference ADs are as under. Please note the difference between Two AD’s:

  • Local AD / Client AD / On-Premises: This is the AD where you have installed Control Panel ADSync Utility. Once ADSync is enabled you can access this local AD and modify user properties on this AD. These changes will automatically be replicated/synced with Provider’s AD (hosted AD).

  • Provider AD / Hosted AD / Cloud AD: This is the AD that is managed directly by Control Panel Control Server via Control Panel Remote Servers.


Settings

Active Directory Synchronization - Settings

Settings will show General & Advanced settings of ADSync.

Fields of the above screen are described below:

General Settings

Fields of the above screen are described below:

  1. Control Panel Url: This is the URL to Control Panel Web Service (provided by host). This can be a Web or IP based address. Check "Tooltip" next to input field for example.

  2. Domain NetBios name: Local-AD domain NetBios name input field.
  3. Service Account: Local-AD administrator account with permissions to perform local operations.
  4. Password: Password for local-ad admin user provided in above field.

Advanced Settings:

  1. Sync Data Attribute: Sync Data Attribute is used to capture the updating password info and store its hash in this attribute. Previously this was fixed to 'division' attribute of Active Directory User, but now can be customized to any valid writable Active Directory User attribute. Note that this attribute is used to temporarily store (encrypted hash) password before syncing it to hosted user and as soon as user password/info is synced in next sync cycle it is cleared from the active directory attribute.
  2. Sync Data every: You can specify Sync interval or use Sync Now option.
  3. Logging Enabled: Enable/Disable logging. Simple check/uncheck input to whether to enable logging or not.
  4. Logs Folder: This is log Path. Select log folder to create log files in there if logging is required. The log folder path of ADSync logs should not be of PDC desktop, and the provided log path should also be present on all ADC.
  5. Purge Logs after: Select number of days after which logs are cleared from the ADSync folder.

Settings are saved on pressing the Save button.

Important: Control Panel Service URL should be accessible from Client-AD.


Add Profile

Active Directory Synchronization - Add Profile

Under "Profiles" you will see listing of existing profiles. Click Add Profile to add a new profile.

Local Organization

  1. Organization: Input field to set Local-AD/On-Premises organization LDAP, or use Icon on the right to list all local organizations and select one of the organizations. This field is editable so you can even specify the ROOT so that ALL USERS under this AD get listed all at once. You can specify the ROOT if users are under different OUs and you want to list all of them in a single go. In case of large ADs it is recommended to use specific OUs only to keep this quick as it will take long time to load all users in case of large ADs.
  2. User custom filter: Define a filter for Users. See details Custom Filters.
  3. Sync Security Groups: In order to Sync security Groups from Control Panel for ADSync Enabled organization check option Sync Security Groups.
  4. Group custom filter: Define a custom filter for security groups.
  5. Auto Create New User: Allows you to enable / disable auto creation of Local-AD user on the Hosted AD. This option enables the customer that any new user created in local OU for this profile will be automatically created on hosted.
  6. Enable user auto mapping: Enable/Disable auto mapping of all existing users. This option enables the customer that all the existing users will be auto mapped to selected hosted organization on the basis of UPN and DisplayName respectively.

Hosted Organization

  1. User Name:Login Name to access the customer account in Control Panel in format: user@domain.com. This is owner of Hosted Organization which needs to be synced with Client-AD. This can either be a Customer Account or a Contact of Customer. In ADSync we need Customer credentials not Reseller/Provider credentials to fetch list of OU’s. List of all OU’s related to Customer are fetched.
  2. Password: Password for user login provided in service user name.
  3. Target OU: Once above service credentials are provided then hosted organizations enabled for ADSync are listed in the selection input box, select one of the organizations to synchronize its contents. Only the organization(s) owned by single customer (whose credentials are provided) are shown.

Add: Adds a profile to the below profiles listing.

Important: "Username" and "Password" i.e. Login Name and Password to Access the Control Panel customer account who is owner of Hosted Organization which needs to be synced with Client-AD. This can either be a Customer Account or a Contact of Customer in control panel.


Configure Mappings

How To Configure Mappings?

Go to Profiles and click Mapping to choose mapping between Hosted and Local User.

  1. Check Enable Sync for users that need to be synced. See the snapshot below:
  2. For users which exist in Local domain but have no counterparts on the hosted AD, you can "Enable Sync" and then auto create them in Hosted platform by choosing "--Create New--".

Important Notes:

  1. ADSync needs to be installed on Primary and all Additional Domain Controllers.
  2. After installation on all Additional Domain Controllers copy SyncConfigurations.xml from ADSync installation folder on Primary Domain Controller to each Additional Domain Controller in the installation directory of Adsync.
  3. Make sure "Password must meet Complexity Requirements" is Enabled in Local domain policy.
  4. To start ADSync to function you need to force all users to change password on On-Premises (Local/Client) AD, please do expire all user passwords and restart all domain controllers

User mapping Example

Let’s assume Hosted AD having the following user.

User.one@livead.com

User.two@livead.com

User.xzy@livead.com Display Name: Gorge John

And local AD having the following Users.

User.one@livead.com Display Name: Gorge John

User.abc@localad.com

User.One@localad.com

User.new@Localad.com

#3 from LiveAD will be matched with #1 on LocalAD based on Display Name.
#1 from Live AD will be matched with #2 of LocalAD based on UPN.

It is shown in tabular form as below:

Local AD | Hosted AD | Comments
User.one@livead.com | User.one@livead.com | Mapped by user ID (Exact match)
User.One@localad.com | User.two@livead.com | Mapped by user ID (Partial match)
User.abc@localad.com | User.xzy@livead.com | Mapped by display name (gorge John)
User.new@Localad.com | --Create New-- | It will create new user On Hosted AD

When Enable Sync is checked, It will synchronize the local user with Hosted AD or will create user on Hosted AD on Save.


Custom Filters

In "Custom Filter" for user and groups we need to specify sync group and sync user in the group and users description (Any attribute can be used). Below are examples to use Custom Filter for Users and Group which uses "sync user" and "sync group" description. In below snapshot UserA, UserB, UserC, GroupA and GroupB, GroupC are created in Active Directory.

Example 1:

In this example we have specified "sync user" and "sync group" description in custom filter and as a result UserA, UserB and GroupA and GroupB (which have description) will get synced. See below snapshots:

Filter settings

Users custom filter: (description=sync user)

Groups custom filter: (description=sync group)

Example 2:

When we specify below custom filter settings in sync group and sync user description that we need not to sync (any number of attributes can be used) for e.g.

  1. Specify something in company for users that I don’t want to sync
  2. Specify something in display name for groups that I don’t want to sync

only UserA and GroupA will get synced as shown below:

Filter settings

Users custom filter: (&(description=sync user)(!(company=*)))
Groups custom filter: (&(description=sync group)(!(displayName=*)))

Example 3:

To show and sync Active Users only, the attribute that will be used is userAccountControl. This attribute has following properties:

  1. 512 -> Enabled
  2. 514 -> Disabled
  3. 66048 -> Enabled, password never expires
  4. 66050 -> Disabled, password never expires

You can use this attribute in a way if you want to extract only active users, example given below will extract only active users.

Filter settings

User custom filter: (|(userAccountControl=512)(userAccountControl=66048))

Filter expressions guides:

https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx

https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax


Operation

How does the utility update the information & how it should be operated?

Normally it should take minimum 5 minutes to update the information from On-Premises to Hosted server. Below is a step by step process how shall this utility be operated.

  1. Save Basic configurations in utility on DC.

  2. Copy SyncConfiguration.xml file from Primary Domain Controller (PDC) installation folder to all ADC(s) ADsync installation directory.

  3. Provide On-Premises to Hosted user mapping using the ADSync config studio.

  4. After providing the mapping, modify the On-Premises Active Directory user account information (Including password).

  5. To force the sync process to start immediately, Click to Sync Now on Adsync configuration studio.

  6. This shall update the information to the control server.

  7. From there, control server uses provisioning service to update the data on associated backend Hosted active directory server.

  8. In Adsync Configuration Studio there are two new controls i.e. Custom Filters and Sync Security Groups

    1. Users Custom filters

    2. Groups Custom Filters

  9. When the option "Sync Security Groups" is checked, Groups will also be synced, but there is no mapping interface like users.

  10. This shall update the On-Premises active directory user information to the Hosted active directory user. Also if logging is enabled from config studio, then send us the log files generated from inside the selected folder to review those files and troubleshoot the problem.

How to run a test case?

  1. Create an AD user in local/client/On-Premises AD under one of the configured Sync Profile.
  2. Open ADSync Configuration Studio and provide mapping for this newly created user (you can use ‘Create New’ option) or if you have enabled ‘Auto Create New user’ option for the selected Sync Profile then leave this step.
  3. Restart ADSync-Svc on local/client/On-Premises AD machine
  4. Now get to hosted Control Panel Control server
  5. Open the database and check ‘Hb_tblTempData’ table, whether it has a pending entry in it or not ?
  6. If there are pending records in ‘Hb_TblTempData’ then restart Provisioning-Svc on Control server
  7. Check in Control Panel whether the user is created on hosted or not. You can use following navigation path: Home > Service Director > Active Directory > Users
  8. Also you can check the Audit logs in the Control Panel interface for sync process. (for filtering select ‘ADSync’ in event groups and press search button)


Enable Logging

Control Panel generates logging for ADsync on Control Server and remote servers in Logs Folder. You can set auto delete files from Control and remote server(s) after selected number of days.

Control Panel Advanced Logging

Control Panel also generates Advanced logging for Ad-sync. Navigate to the following path:

Navigation: Home » System Configuration » Logging

Now enable Advanced logging from Control Panel interface as shown below:

ADSync Logging

In ADSync Configuration Studio, Please checkbox Logging Enabled and select selecting the Logs Folder as shown below:

You can also clear logs by providing number x of days in Purge Logs After.


Types of Adsync Logs

Different Types of Logs for ADSync

The Adsync logs are generated on following servers:

  1. ADSync Client Server
  2. Control Panel Server.
  3. Remote Server(s)

1. ADSync Server Logs

These logs are generated on ADSync Client Server. It is the server where ADSync is installed and logs are generated in User specified log folder. You can find following types of logs in logs folder.

  1. ADSyncSvcLog-DateStamp.txt
  2. AutoMappingLog-DateStamp.txt
  3. SyncLog-DateStamp.txt
  4. UserMappingLog-DateStamp.txt

a. ADSyncSvcLog-XX-XXX-XXXX

This log will give you details about Sync Thread Started or Not. It will do the following details:

  1. Fetch list of all user under LDAP
  2. Give status How many User Uploading
  3. Give Status for sync job with Date, Time of new user from Hosted to Client AD

b. AutoMappingLog-XX-XXX-XXXX

If you enable auto mapping in the Ad sync Configuration This log will give you following details:

  1. Retrieved user list & calculate quantity
  2. Sort them by UPN from local AD & then from Hosted side
  3. Start Mapping automatically with Date, Time & complete UPN name of individual user
  4. Skip already mapped user to avoided adding extra group jobs.

c. SyncLog-XX-XXX-XXXX

This log created with Temporary Log ID for details troubleshooting with last USN value of the user that was synced.

  1. Check all of individual user attributes under attribute editor
  2. In case any change in any attribute of user it will perform sync
  3. Save User UPN & Changes
  4. Skip in case no change in USN for all user
  5. Saved last USN figure with Date & Time for Next

d. UserMappingLog-XX-XXX-XXXX

This type of logs contain records of all user mapping activities auto/manual with any UPN change.

  1. Check total no of user from Adsync configuration file
  2. Check auto mapping & manual mapping
  3. Check local user UPN with previous binding to hosted user
  4. Match Exact & Partial UPN, Display name, with hosted user & readjust the value if needed.
  5. Give complete sync operation with UPN, Time & Date.

2. Control Server Logs

On Control Server the logs are created in Logs Folder.

ADSyncExceptions-datestamp.log

3. Remote Server Logs

On Remote server (Exchange) the logs are created in Logs Folder.

ADExceptions-datestamp.txt


Access is denied

Troubleshooting Note 1

Error / Problem Statement:

Access is denied when saving the ADsync configuration or saving user mapping.

Cause:

The utility is trying to access a system resource (local file or active directory object) and has no sufficient privileges for read/write operation.

Resolution:

  1. Please check that the user account provided in ‘Admin Login/Admin Password’ fields of ADSync configuration studio has sufficient permissions set to the ADSync installation directory and also to the selected logs folder. If not then provide read/write permission for provided user account
  2. Also check that the utility is running under a user account which has access (read/write) to the installation directory and to the log files directory.
  3. Please check that the user account provided in ‘Admin Login/Admin Password’ fields of ADSync configuration studio has valid permissions in active directory for all the local organizations (OUs) selected in sync profiles.


Authentication Exception

Troubleshooting Note 2

Error / Problem Statement:

Authentication Exception when trying to fetch hosted organizations from control server or hosted organizations are not listing/fetched.

Causes:

  1. Sync web service at control server end is unable to validate the request due to invalid credentials provided for ‘service username or service password’

  2. For hosted organizations not listing, the service provider may not have enabled the ADSync option from control server

    (Home > Service director > Active Directory > Organizations)

Resolution:

  1. Please provide valid credentials for the fields ‘service username/service password’. These must be the credentials which are used to login to customer portal of Control Panel. You can even option control panel URL on the AD server to ensure control panel URL is accessible and that using the credentials you are able to login as End Customer which is owner of organization in question.
  2. Please verify that the organizations under the selected customer are enabled for ADSync from control server (Home > Service director > Active Directory > Organizations). You have to login as provider and enable ADSync for the organization.


Information not Syncing

Troubleshooting Note 3

Error / Problem Statement:

Information not syncing to the hosted.

Causes:

There are several reasons due to which the ADSync may not be syncing information to the hosted active directory:

  1. ADSync service is not running on client AD
  2. Sync configuration is corrupted.
  3. Data is uploaded but not syncing due to provisioning service on control server i.e. "Provisioning Service" is not running or having some error.

Resolution:

There is no single resolution to this situation. Below are some guidelines to trace out the problem.

  1. Please confirm ADSync svc is running on client AD.
  2. Re-configure the sync profiles (See Also: Re-configure sync profiles)
  3. Share logs with support from ADSync client logs folder and Control Panel control server (ADSyncExceptions) logs folder. See Also: Type of Logs


Passwords not Syncing

Troubleshooting Note 4

Error / Problem Statement:

All information is syncing other than the password (password not syncing).

Cause:

In this case we do have multiple scenarios which are resulting in failure to sync passwords for local users to hosted.

Resolution:

Please see below check list for resolution to this problem.

  1. In active directory on client platform “password must meet complexity requirements” under local security policy is set to true
  2. VC++ 2010 runtime is installed (specific to OS platform i.e. x86/x64) on all PDC/ADC
  3. Check that ‘ADSyncPolicy.dll’, ‘ADSync.PolicyLogger.dll’ and ‘ADSync.ClienHelper.dll’ files are placed inside the ‘$windir\System32’ directory on all PDC/ADC
  4. Check that there exists an entry for ‘ADSyncPolicy’ in following registry path ‘HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Notification Packages’ on all PDC/ADC
  5. Are all the PDC and ADCs rebooted after installing and configuring the ADSync tool ?

If all of the above checklists are correct then the reason of issue may be configuration problem. Please perform following steps.

Re-configure the ADSync/Sync Profiles:

  1. Delete all instances of the 'SyncConfigurations.xml' file from ADSync host on all PDC/ADC. Even look for this file on other location because those instances may create issues too. You have to be sure that only 1 file exists after your configuration is completed. So, if you are looking for a complete fresh configuration, DELETE ALL SyncConfigurations.xml files.
  2. Close ADSync configuration studio, re-open and re-configure sync profiles.
  3. Copy the updated 'SyncConfigurations.xml' file from PDC ADSync installation director to each Additional Domain Controller. Registry on both types of servers will tell you correct location for configuration file. For old clients the path will be C:\Windows\System32 folder, and for new clients the path to place this file will be C:\Program Files\ADSync. You can confirm/fix the Registry for correct location of SyncConfigurations.xml.
  4. Open the user mapping screen and unselect mapping for all the users by clicking twice on ‘select all’ box on top right of the users listing and then press save.
  5. Exit the user mapping screen.
  6. Open the user mapping screen again and provide/verify appropriate user mapping and then press save.


ADSync License error

Troubleshooting Note 5

Error / Problem Statement:

User syncing will stop at local AD data of User being sent normally but not being synced.

Cause:

ADSync user license limit reached.

Resolution:

  1. In this case you have to look into logs at control server Logs Folders (File: ADSyncExceptions) ADSync Error: ADSync license error: ADSync user license limit reached.
  2. Contact Support\Sales to update licenses. After updating licenses, User syncing will start working again as per ADSync Configuration.


ADSync Service Not Starting

Troubleshooting Note 6

Error / Problem Statement:

Windows could not start the ADSync service on Local Computer. "Error1607: The process terminated unexpectedly."

Cause:

You will face following issue if Log path in ADSync Registry is incorrect

Resolution:

It should be same as C:\Program Files\ADSync\Logs as shown in the snapshots below:


Security and Password Policy

Password policy should remain consistent between source (client) AD and Hosted (Cloud) AD, meaning that both ADs should have similar password policies. It is best to have Complex Password Policy. Also there is no need to select the ‘reversible password’ option in source (client) AD for syncing password.

Password for a user account is secured by modern encryption schemes and is stored in a secured place.

To make communication even more secure, one must apply/enable SSL certificate for Control Panel website and use the ADSync Web Service address as https:// (like https://cp.providerdomain.com/webservices/Adsyncsvc.asmx)