Running the LDAP sync agent

As an LDAP administrator, you can run the LDAP sync agent to sync user groups only, users only, or user groups and users along with their mapping.

The agent syncs the newly added or updated user groups and users from LDAP, but it does not remove the user groups and users that are deleted from LDAP. The unwanted user groups and users must be deleted manually from the BMC Helix Portal console.

Before you begin

Ensure that the following tasks are completed:

• JDK version 11 or later is installed on the computer on which you want to run the LDAP sync agent and the JDK path is set in the PATH variable.
• Download and configure the LDAP sync agent. 
• Create a tenant-level access key or a user-level access key with the appropriate permissions to create, modify, list, and read objects. 
• Create an external user with the same login ID as the LDAP admin user or create a default role. Ensure that the external user or the default role has all the permissions for the Identity Management Service application or service at a minimum. For more information, see User identities.
• Ensure that Helix Single Sign-On is configured to authenticate users with your LDAP server details. Contact BMC Support to configure Helix Single Sign-On as described in  Configuring authentication .

To run the LDAP sync agent

1. Open command prompt from the bmc_helix_identity_sync_agent folder.

2. (Optional) Check whether the parameter configuration details provided earlier are runnable and can be parsed correctly by running the following dryrun command:

   • (Windows) ldap-agent.bat -d <objecttype>
   • (Linux) sh ldap-agent.sh -d <objecttype>

   The <objectType> value can be groups, users, or all based on the objects that you want to preview.
   By default, the top 10 results are displayed. To see the complete list, see the logs available under the bmc_helix_identity_sync_agent\logs folder.

3. (Optional) Check the agent versionby running the following command:
   • (Windows)ldap-agent.bat -v
   • (Linux) sh ldap-agent.sh -v 
4. Start the agent to perform a one-time sync or a recurring sync of the objects specified in the application.properties file located at bmc_helix_identity_sync_agent\config by running the following command:
   
   • To perform a one-time sync:
     
     • (Windows) ldap-agent.bat -r
     • (Linux) sh ldap-agent.sh -r  
   • To perform a recurring sync:
     
     • (Windows) ldap-agent.bat -s
     • (Linux) sh ldap-agent.sh -s

   Important

   If you change any parameter configuration details in the application.properties file while the sync is in progress, ensure that you restart the agent to rerun the sync. 

   How LDAP groups with duplicate names are synced?

   • If the name of an out-of-the-box user group on BMC Helix Portal matches with an LDAP group, a new external user group is created on BMC Helix Portal.
   • If the name of an existing user group on BMC Helix Portal matches with an LDAP group, the existing group's type is updated from Local to External. The user group retains its existing associations and permissions unless you set the ade.user.group.mapping.replace parameter to true in the application.properties file.

   The synced groups are displayed on the User access > User groups page and the synced users are displayed on the User access > Users page.

To verify that the LDAP sync is complete

1. Open the agent.log file located at bmc_helix_identity_sync_agent\logs.
2. At the end of the file, locate a confirmation message indicating that the sync is complete. 

If the sync is not complete, see the log files available under the bmc_helix_identity_sync_agent\logs folder to review the possible causes. Under the logs folder, user-related failures are logged in the users.csv file and the user group-related failures are logged in the groups.csv file. For assistance, contact BMC Support.

Where to go from here

As a tenant administrator, assign appropriate roles and permissions to the synced user groups and users. For more information, see Setting up roles and permissions.