1. Download the Agent

1. Sign in to Zoho Directory. Click ADMIN PANEL from the left menu.
   
2. Go to the DIRECTORY STORES tab. Click Add Directory.
   
3. Find LDAP Services and click Add.
   
4. On the Download Agent screen:
1. Review the prerequisites.
   
2. Select your LDAP service from the dropdown.
3. Once you select your LDAP service, the system displays an installation key. Copu the Installation Key. 
4. Click Download and wait for the download to complete.
   

2. Install the Agent

1. Execute the downloaded file ZohoDirectory_IdentityConnect.msi to start installation.
   
2. Paste the Installation Key. Upon successful validation, you'll be taken automatically to the setup wizard where you can complete the rest of the installation steps.
   
3. On the Welcome screen, choose your language.
   
4. Read the software license agreement carefully, then accept the terms. Click Continue. Clicking the URL will not auto-redirect you to the page in some legacy systems. In this case, click 🔗 to copy the URL, then paste it in your browser to read the license agreement.
   
        
   
   
5. Open the provided Login URL from a browser.
   
        
   
   
6. Sign in to your Zoho Directory admin account if you haven't already.
   
7. Enter the Verification Code shown in the installer.
   
8. Upon successfully signing in, a confirmation screen with your Zoho account email and display name will appear. Click Continue.
   
        
   
   
9. Once the agent is installed, complete the sync setup in Zoho Directory.
   

   Possible error cases that appear at this step:

   Error	Fix
   The verification code is time-bound and will become invalid after the expiration time (5 minutes).	Click Retry to generate a new code, which you can use to sign in and proceed to configuring your LDAP settings.
   Sometimes, the agent may not be able to contact the Zoho server due to network issue.	Click Retry. If the error persists, contact support.

   
   

3. Configure Sync in Zoho Directory
   

1. Configure LDAP Connection Details
   

1. This is a crucial step where the agent is allowed to connect with the on-premises directory store to fetch data of users and groups for sync.
   
2. Enter your directory info: Domain Name, LDAP servers, Connection Port, Base distinguishes name, User's distinguishes name, Password. Make sure they're all valid.
   
        
   
3. Enable SSL for a secure connection:
   
1. SSL is recommended, as it safeguards sensitive directory data during transmission.
   
2. To use SSL:
   
1. Your LDAP server must have a valid SSL certificate issued to its domain.
   
2. Use the fully qualified domain name (FQDN) in your LDAP server name field (e.g., ldap-server-1.zylker.com). Using only the hostname will cause SSL failure.
   
4. Click Next to review the LDAP configurations. 
   
   

   If you face the error 'LDAP server goes unreachable,' click Retry to attempt the connection again. Make sure that there's no connectivity issue between the agent machine and LDAP server.

2. Complete Installation
   

1. Click Install to finish setting up the agent. Upon successful installation, the agent will be running.
   Note: Ensure the agent machine maintains continuous network connectivity according to your organization's power-saving or login-based policies.
2. Click  to perform the following actions:
   
1. Change ownership - Switch the Zoho Directory admin account linked to the agent in case the original admin leaves your organization or loses LDAP access.
   
        
   
   
2. Change LDAP settings - Modify your LDAP server details here. After making changes, click Update to save them.
   
3. Go back to the Zoho Directory Admin Panel to complete the remaining setup.
   

3. Configure Sync Options

1. Select Organizational Units (OUs)
   

1. From the Admin Panel, navigate to your required directory using the dropdown provided in the download agent screen.
2. Choose which OUs you want to sync to Zoho Directory.
   
3. Select object types to include:
   
1. Users
   
2. Groups
   
3. Custom LDAP Query - Enter a valid LDAP query and click Save to sync based on specific LDAP attributes.
   
4. Review the chosen OUs:
   
1. Edit or remove any existing OU preferences.
2. To add more OUs, click Add OUs.
   
3. When you're done, click Add and Continue.
   

2. Map Zoho Directory fields with your LDAP fields

1. This is important for making sure user data is correctly transferred.
   
2. Toggle between User Mapping and Group Mapping.
   
3. Fields will be auto-suggested, but you can map them manually.
   
4. Use the tabs to filter by All Fields, Mapped, or Unmapped fields. For example, you can map the Zoho Directory "Last name" field to your LDAP "Surname" attribute.
   
5. For custom attributes:
   
1. Click Edit next to one of the default attributes displayed.
   
2. Select Custom LDAP attribute.
   
3. Enter a name for the attribute and save it.
   

3. Define Sync Criteria
   

1. On the SET SYNC CRITERIA screen, specify which users or groups should be included in the sync. To configure criteria for groups, switch to the Groups tab.
2. Select import type: Based on criteria or All users
   
3. If using criteria, define the Field, Relationship, and Value. Click Save and Next.
   

4. Configure Password Sync Settings

1. Enable the toggle to securely synchronize user passwords from on-premises LDAP-based directories to Zoho Directory.
   
1. Zoho Directory supports only the following hashing algorithms for security: SHA-512, BCrypt, and SHA-256. Ensure the user passwords are hashed using one of these.
   
2. Password updates will be reflected only during scheduled sync or manual import
   

   If a directory-synced user is deleted from Zoho Directory, password changes for that user in on-prem directories will not sync unless the user is re-provisioned in Zoho Directory. 

1. User Sync Settings
   

1. Configure automated rules for user account handling based on changes in on-premises LDAP-based directories.
   

   Setting	What it is for	Options
   Mail Notifications	Choose whether you want to send notifications to synced users.	Notify via mail - Sends emails to newly synced users and resend invite links to pending users.  Don't notify - No email notifications are sent to users.
   Password Notifications	Decide how new users get their initial passwords	Send email OTP to user - The new user will receive an email directly to their registered email address containing an OTP. Send email OTP to admin - Admin will receive the OTP or setup info, which they should then forward to the user manually. Don't notify anyone - No automatic notifications are sent. An admin should manually notify the user and provide them with their login credentials through some other medium on their own.  The Password Notifications section is displayed only when the Notify via mail option is selected in Mail Notifications section.
   Status Sync	Choose how to reflect a user's on-premises account status changes in Zoho Directory.	Change in Zoho Directory - If disabled in on-premises, directory account also gets disabled (and re-enabled if restored). Do nothing - Ignore on-premises status changes.  If Do nothing is selected, the system will no longer manage user status. The When User Leaves Selected OU setting will be disabled and unavailable, as it requires Status Sync to be enabled. Learn more about this interactive behaviour illustrated after the table.
   When User Leaves Selected OU	Define what should happen in Zoho Directory when a user is moved out of a selected/synced on-premises directory OU.	Disable in Zoho Directory - The user's Zoho account is auto-disabled. Do nothing - The user's Zoho account remains active, but will no longer be included in the future sync operations.

1. Important note: There's a crucial interaction between Setting 3 and Setting 4. The When User Leaves Selected OU setting depends on Status Sync. The former is only available if the latter is set to Change in Zoho Directory. If you choose to Do nothing with status changes, the system cannot manage user status based on OU membership. Therefore, Setting 4 will be disabled altogether.
   

   For example, let's assume there's a user named Dexter in AD and see how he's affected during sync with these two settings:

   Status Sync	When User Move Out of Selected OU	Action performed on Dexter (in on-premises LDAP directory)	Result (in ZD)
   Reflect in ZD	Disable in ZD	Dexter is removed from OU but still active in on-premises LDAP directory	Dexter's Zoho account is disabled (OU rule applies)
   Do nothing	(field gets disabled with Do nothing selected)	Dexter is removed from OU	Dexter's Zoho account remains active but is no longer synced (because Status Sync setting is ignoring status changes, and OU-based handling is off)
2. Reflecting hard deletion of users from on-premises LDAP-based directory to Zoho Directory:
   When Zoho Directory Identity Connect is enabled, your on-premises LDAP-based directory acts as the primary source for user discovery. If a user is deleted or disabled in on-premises LDAP-based directories, the corresponding action in Zoho Directory depends on the configured Status Sync setting.
   

   When Status Sync is set to Change in Zoho Directory, users disabled or deleted in on-premises LDAP directories are disabled in Zoho Directory.
   If your organization requires users to be completely deleted from Zoho Directory instead of just disabled, contact Zoho Directory Support to enable this configuration for your account. Enabling deletion propagation will permanently remove users in Zoho Directory when they're disabled/deleted in on-premises LDAP-based directories.
   

   For step-by-step instructions on deleting users and handling ownership transfers, see How to Delete a User
   

   Note on admin deletion: Each Identity Connect configuration is associated with a Zoho Directory admin. To ensure uninterrupted sync, the system will not allow the deletion or disablement of an owner-admin. 
   You must first use the Change Ownership option in the tray app to transfer dependencies to another admin; only then can the original account be removed. You must reassign ownership to another admin. If you attempt deletion directly, the system will block the action and place them in a "delete-pending" state until all dependencies are cleared.
   
1. Deleting a directory-synced user from Zoho Directory: Deleting a user in Zoho Directory does not remove the user from the on-premises LDAP-based directories.

   Warning on data loss: If "Delete in ZD" is enabled, removing a user from on-premises LDAP directories will permanently erase their Zoho mail, files, and service data. This data cannot be recovered even if the user is re-synced later from the LDAP directories.

   COMMON SYNC SCENARIOS AFTER USER DELETION

   The following scenarios illustrate common outcomes based on typical configurations. Actual results depend on sync criteria and status settings.
   

   
   

   Scenario	Action in ZD	Action in on-premises LDAP directory	Manual Sync Result	Scheduled Sync Result
   Manual re-creation	User deleted	User exists & meets criteria	User appears in "Users to Create"	User is automatically re-created
   Complete removal	User deleted	User deleted	No action	No re-provisioning (user remains deleted)
   Mixed Zoho & on-prem LDAP directory actions (or) Conflicting actions	User deleted	User deleted User disabled/moved out of synced OU	Depends on Status Sync setting	Depends on Status Sync setting

   
   

2. Schedule Sync
   

1. Set frequency (Daily/Hourly/Weekly/Monthly) and time of sync. Click Save and Next.
   Changes in LDAP directories are reflected based on the configured sync schedule and may not appear immediately in Zoho Directory.

3. Review and Finalize Sync

1. Review and select users from the imported list to add to Zoho Directory. This screen helps you with the following filters:
   
1. New Users - Users found in your directory but not yet in Zoho Directory.
   
2. Users to Update - Existing ZD users whose info will be updated from your directory in the next sync.
   
3. Marked for Activate/Disable - Users who will be activated or disabled based on their status in your directory. Review this category carefully before syncing to avoid unintended changes to user access.
4. Ignored - Users who do not meet the configured sync criteria
2. Click Add and Continue.
   
3. Review the summary and click Finish to complete the setup. 

Actions that can be performed using the trap app:

1. Click the icon to perform the following actions:

1. Change ownership - Change the Zoho Directory admin account linked to the agent when the current admin is no longer with your organization. If the current Zoho admin is the directory store owner, you must first transfer the store ownership to another admin before updating the linked admin account.
   
2. Change LDAP settings - Modify your LDAP server details here. After making changes, click Update to save them.

Troubleshooting the "Disconnected" Status

1. Verify that the machine has active internet connectivity.
2. Ensure the system date and time on the machine are correct.