Managing the AD Sync Tool

The AD Sync Tool is a command line tool that you can run on a Windows, Linux, or macOS system to sync users and groups between your Active Directory (AD) or LDAP Server and your Zoom account. With this tool, you can automatically manage users and groups in your Zoom account when there is a change in your LDAP/AD system for those users and groups.

The tool runs in the console, and does not include a GUI or web interface. Settings are configured using a properties file, and you can check the log files to see the change details or to troubleshoot any errors.

Based on changes in your LDAP/AD server, the AD Sync Tool allows you to create, update, and deactivate/delete users, update the Zoom user's email (the new email's domain must be in the associated domain), and sign users out when their password has been changed, deleted, or disabled. This tool also allows you to create, update, and delete Zoom groups as well as add or remove group members.

The AD Sync Tool supports the following attributes.

User:

• First Name
• Last Name
• Email
• Department
• Job Title
• Phone Number
• Company
• Cost Center
• Employee Unique ID

Group:

• Group Name
• Group Email Alias

Requirements for the AD Sync Tool

• A Zoom account with the following features enabled:
  • Vanity URL
  • REST API
  • Active Directory
  • Single Sign On has been enabled and configured in Zoom 
  • Submit a request to Zoom Support to enable AD Sync Tool
• Create Server-to-Server OAuth app for the AD Sync Tool on the Zoom App Marketplace
• LDAP services, such as Active Directory Federation Services (ADFS)
• LDAP (or Microsoft AD) admin account for which you have access to the username and password

How to create a Server-to-Server OAuth app for the AD Sync Tool

Verify permissions to edit users

To create this app, the user must have User:Edit permissions.

1. Sign in to the Zoom web portal as an admin or user with role management edit permissions.
2. In the navigation menu, click User Management then Roles.
3. On the All tab, click the name of the role type you want to check, such as Admin.
4. Under User and Permission Management, verify that this role has Edit permissions for Users.

Learn more about role management.

Create the app

You must create a Server-to-Server OAuth app for the tool on the Zoom App Marketplace. Only users with User:Edit permissions can complete this task.

1. Sign in to the Zoom App Marketplace.
2. In the top-right corner, click Develop then Build Server-to-Server App.
3. Enter a name for your app and click Create.
4. On the App credentials tab, view your account ID, client ID, and client secret. You'll use these credentials to authenticate with Zoom.
5. On the Information tab, add information about your app, such as short description, company name, and developer contact information (name and email address required for activation).
6. On the Scopes tab, click Add Scopes, then add the following scopes:
   1. Click User, then click View users information and manage users and select the Remove a user's token scope.
   2. Click SCIM2, then click Call Zoom SCIM2 API and select the Call Zoom SCIM2 API scope.
   3. Click Done.
   4. Click Continue.
7. On the Activation tab, activate your app.

Quick start of the AD Sync Tool

1. Install JDK version 17 or higher, then run the following command to make sure that java is installed correctly:
   java -version
2. Obtain the zoomadsynctool.zip file from the following location: https://cdn.zoom.us/prod/tools/zoomadsynctool.zip
3. Unzip the zoomadsynctool.zip file.
4. Back up and update the config.properties file, as described in the Configuration section.
5. Prepare a secret code to protect the sensitive information in the tool configuration files. The secret code is required every time you run the tool.
6. Complete the tool's initialization configuration by running the following command:
   bin/adtool.cmd setup
7. Validate the accuracy of the config.properties file and the results of the synchronization by running the following command:
   bin/adtool.cmd preview
8. Modify the config.properties file and your LDAP/AD users/groups, then run the preview command again to verify whether the results meet your expectations.
9. When the configuration is correct and the preview command results as expected, start the synchronization operating by running the following command:
   bin/adtool.cmd sync
   Caution: Running the sync or start command can delete or deactivate existing users from your Zoom account if those users do not exist on Active Directory. Refer to the Zoom account configuration:
   zoom.allow.delete.missing.user
   Note: If there is a large amount of data to synchronize, this command will take some time to execute. Please refrain from performing any additional operations during its execution.
10. (Optional) Continuously monitor and synchronize any changes in your LDAP/AD system by running the following command:
    bin/adtool.cmd start
    Note: Start the AD Sync Tool as a daemon service. It will continue to run incremental synchronization every 40 minutes. It will also monitor password change events.
11. Check the log file if you fail to run any command.

How to configure the AD Sync Tool

The config.properties file includes a set of parameters that determine how the tool will perform the synchronization. There are two types of synchronizations you can perform:

• Full sync: Compares all the Zoom users/groups and AD users/groups, and synchronizes all AD users and groups to Zoom.
• Incremental sync: Only synchronizes the changed AD users/groups to Zoom since the last sync.

You must update the values in the following sections of the file.

Note: Credentials should not be added in this file.

Zoom setting (updated values required)

• zoom.vanity.url: Your Zoom vanity URL.

Sync options (updated values required)

• zoom.default.user.type: The default user type when provisioning a new Zoom user. The user types are 1: Basic, 2: Licensed, and 3: On-Prem. The default value is 2.
• zoom.allow.create.user: Determine if you want to create new Zoom users when these users exist in your AD. The values are true: create new users and false: do not create.
• zoom.allow.update.user: Determine if you want to update Zoom users when these users are different from your AD. The values are true: update and false: do not update.
• zoom.allow.delete.user: Determine if you want to delete Zoom users when the users are removed from your AD. The values are true: delete and false: do not delete.
• zoom.default.user.delete.behavior: Determine if you want to delete or deactivate the user from Zoom when performing a "delete" action. The values are 1: deactivate or 2: delete. The default value is 1. This depends on zoom.allow.delete.user or zoom.allow.delete.missing.user.
• zoom.allow.delete.missing.user: Determine if you want to delete users from Zoom if these users do not exist in AD when in a full synchronization command (when this tool is run for the first time). The values are true: will delete missing users from Zoom and false: will not delete missing users from Zoom. The default value is false. If you do not want to impact your existing Zoom users, choose false.
• zoom.allow.sync.group: Determine whether to sync groups between your AD and Zoom. If you allow group sync between your AD and Zoom, leave “ldap.servers[0].groups” blank in the LDAP/AD setting. The values are true: will sync groups between your AD and Zoom and false: will not sync groups.
• zoom.allow.create.group: Determine if you want to create new Zoom groups when these groups exist in your AD. The values are true: create new groups and false: do not create.
• zoom.allow.update.group: Determine if you want to update Zoom group information (such as name or email alias) or to add and remove group members. The values are true: update and false: do not update.
• zoom.allow.delete.group: Determine if you want to delete Zoom groups when the groups are removed from your AD. The values are true: delete and false: do not delete.
• zoom.monitor.job.interval.minutes: The execution interval of the monitor job. The default interval is 15 minutes.
• zoom.incremental.sync.job.interval.minutes: The execution interval of the incremental sync job. The default interval is 40 minutes.

LDAP/AD settings (updated values required)

This tool supports multiple LDAP/AD server connections. The value "n" identifies the index of the LDAP Server. The value of n starts from 0.

• ldap.servers[n].url: The LDAP server URL for the LDAP server or Active Directory server.
• ldap.servers[n].base: The base folder location for locating users.
• (Optional) ldap.servers[n].groups[m]: The full DN for a user group. If this value is empty, users from all groups will be synced to Zoom. If you specify a DN for a user group, only members in the specified group will be synced to Zoom. Set it to empty if you do not want to filter users by group. You can set up multiple groups for one server, and the value "m" identifies the index of the group. This item is empty by default.
• (Optional) ldap.servers[n].deletedBase: The base folder location to search for deleted items. The default is: CN=Deleted Objects,{Your LDAP Base Name}. You can update the values to reflect the environment.
• ldap.default.query.pageSize: The LDAP server return maximum users/groups in one page/query.

Attribute mapping (updated values optional)

• ldap.user.email: The email field name in AD. The default value is userPrincipalName.
• ldap.user.firstname: The first name field name in AD. The default value is givenName.
• ldap.user.lastname: The last name field name in AD. The default value is sn.
• ldap.user.department: The department field name in AD. The default value is department.
• ldap.user.phoneNumber (disabled by default):  The telephone number field name in AD. The default value is telephoneNumber.
• ldap.user.jobTitle (disabled by default): The job title field name in AD. The default value is title.
• ldap.user.company (disabled by default): The company field name in AD. The default value is company.
• ldap.user.employeeId (disabled by default): The employee unique ID field name in AD. The default value is employeeID.
• ldap.user.costCenter (disabled by default): The cost center field name in AD. There is no default value. You must choose the attribute.
• ldap.group.name (disabled by default): The group name field name in AD. The default value is cn.
• ldap.group.email (disabled by default): The group email alias field name in AD. There is no default value. You must choose the attribute.

Notes:

• If you comment or uncomment the mappings, you must run a full sync for it to take effect.
• There are three mandatory mappings: ldap.user.email, ldap.user.firstname, and ldap.user.lastname. Do not disable them.
• All mapping values are case-sensitive. To get the correct field name for mapping in ADFS, go to Server Manager > Tools > Active Directory Users and Computers > [Select a target user] and right-click Properties, then go to Attribute Editor > Attribute Column.

Logging setting

• log.dir: Set the base directory for log files. You can use a relative path like . or .., or an absolute path like C: or D:. The default is .(current adtool- ${version} .jar file location).

Sync commands

• General options:
  
  • Display help information for the tool. 

    -h, --help

  • Display version information of the tool. 

    -v, --version

• Command options:
  • Display help information of this command.

    -h, --help

  • Specify to run as a service mode and does not require entering the secret code.  

    --service

setup

Configure the credentials for Zoom authentication and LDAP authentication. If you want to change some
credentials, you can run the setup command to update. When running this command, you will be
asked to enter the Zoom Account ID, Client ID and Client secret, AD username and password.

Setup flow:

1. Enter the secret code.
2. Confirm the secret code.
3. Enter the Zoom Account ID (Copy from Server-to-Server OAuth app).
4. Enter the Zoom Client ID (Copy from Server-to-Server OAuth app).
5. Enter the Zoom Client Secret (Copy from Server-to-Server OAuth app).
6. Enter the user DN (distinguishedName) of the LDAP server.
7. Enter the user password of the LDAP server.
   Note: The secret code, Client Secret, and password are not visible when editing.

start

Start the AD Sync Tool as a service. It will run a full synchronization for the first time and start a job to run incremental synchronization every 40 minutes until you shut down the tool. Additionally, the tool will monitor the password change event. By using this command, you don't have to create Task Scheduler or CRON in the system.

preview

Preview the synchronization result without making changes to your Zoom account. This is helpful if you want to ensure options in the tool work as expected.

reset

Reset the settings for this tool. It will clean all of your local configuration and cached data for the tool. If you fail to run this tool for any reason, you can run the reset command to make it work again.

sync

• Option to specify to run a full sync: 

  --all

Run one full or incremental synchronization from LDAP to Zoom. We recommend running preview to check the result before running a full sync. If a full synchronization has ever been executed, it will run an incremental synchronization. If you want to run a full sync, append "--all" for the sync command.

monitor

Monitor the user's password change event and force logout the Zoom user from all devices when the password in LDAP/AD changed. This tool monitors the event that the LDAP/AD user password has been changed, and it cannot obtain the passwords of the LDAP/AD users.

test

Test if the configuration is working. It will use the credential to test the connection and authentication for LDAP/AD server and Zoom.

Examples of command executions for the AD Sync Tool

The common execution script pattern is: bin/{script file} {command}.

• For a Windows system, {script file} is adtool.cmd
• For a Linux or macOS system, {script file} is adtool.sh

Examples for help/version information of the tool

Display help information of the tool:

bin/{script file} -h
bin/{script file} --help

Display version information of the tool:

bin/{script file} -v
bin/{script file} --version

Display help information of the setup command:

bin/{script file} setup -h
bin/{script file} setup --help

Examples for set up the tool

Set up the tool in the default mode:

bin/{script file} setup

Set up the tool in the service mode:

bin/{script file} setup --service

Reset the tool:

bin/{script file} reset

Examples for run the tool

Run the tool in default mode:

bin/{script file} start
bin/{script file} sync
bin/{script file} preview
bin/{script file} monitor
bin/{script file} test

Run the tool in service mode:

bin/{script file} {command} --service

How to run the tool as a service (Windows)

Prerequisite:

Run the following command to set the service mode (Note: Running "bin/adtool.cmd setup" will remove the service mode):

bin/adtool.cmd setup --service

• Start: To start the tool to run in the background process, double-click the start.bat file in the bin directory. Check the running status in the log file.
• Stop: To stop the process that is running the tool, double-click the stop.bat file in the bin directory.

How to start automatically after system startup (Windows)

1. From the Start menu, go to Windows Administrative Tools, then click Task Scheduler.
2. On the Action menu, click Create Task.
3. On the General tab, do the following:
   1. Enter a name for the task, for example "ADSyncToolTask".
   2. Under Security options, select the Run whether user is logged in or not option and the Run with the highest privileges check box.
4. Click the Triggers tab and do the following:
   1. Click New.
   2. On the Begin the task drop-down, select At startup.
   3. Click OK.
5. Click the Actions tab and do the following:
   1. Click New.
   2. On the Action drop-down, select Start a program.
   3. Click Browse, choose the start.bat file in the bin directory, and click Open.
   4. Click OK.
6. Click the Conditions tab and do the following:
   1. Under Power, clear the check box next to Start the task only if the computer is on AC Power.
   2. Click OK.
7. Click the Settings tab and do the following:
   1. Leave the Allow task to be run on demand check box selected, and clear all other check boxes.
   2. Click OK.
      The tool will start automatically after the next system restart.

AD Sync Tool log files

Use the log files to see the details of the records that were synchronized and to help with debugging any sync failures. A maximum of one of each type of log file is generated each day. If you run the Zoom AD Sync tool multiple times in the same day, the information from that run is appended to the file that was previously generated for that day.

• zoomadtool-sync.yyyy-MM--dd.{num}.log: This is the common log for the tool to check for errors.

Abnormal data files

Use the abnormal data file to view details about abnormal user/group data during the full synchronization.

• abnormal-data-yyyMMdd-HHmmss.txt: This is the file used to record abnormal data.

AD Sync Tool security

Enabling SSL/TLS connection for ADFS

If you are using LDAPS via port 636 to connect to an Active Directory server using SSL, the SSL certificate must be retrieved and installed, or you may receive the following errors:

"The server requires binds to turn on integrity checking if SSL\TLS are not already active on the connection..."

or

"sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target."

Retrieving and installing the SSL certificate

To import the SSL certificate and connect the AD Sync tool via TLS:

1. Open the Windows Management Server Manager.
2. Under Tools, open the Certification Authority.
3. Under Issued Certifications, right-click on the desired certificate.
4. Click Properties.
5. Click the Details tab.
6. Click Copy to File, and choose the Base-64 encoded x.509 (.cer) for exporting.
7. Click Next to export the certificate.
8. Copy the exported certification to your local device storage (ex. D:\ca.cert).
9. Open the Command Console, and run the following change directory command to access the Java JDK bin location: 
   

   cd C:\Program Files\Java\Jdk1.8.0_201\bin

   Note: This folder may not be in the exact path as above, and the command will need to be altered if the actual folder path is different.
10. Run the following command to copy the certificate to the new location:
    

    keytool.exe -importcert -keystore ..\jre\lib\security\cacerts -storepass changeit -file D:\ca.cer -alias myca

    Note: The command structure is based on the following:
    • **-keystore**: Where the new certification stored. No need to change this.
    • **-storepass**: The certification's password.
    • **-file**: The certification location you just exported.
    • **-alias**: The alias of the new certification.
11. Once complete, the certificate will be imported and installed. Update the LDAP/AD URL to the ldaps://[address]:636.