Active Directory Sync Tool

The Sync Tools feature will allow administrators to synchronize groups of users to the DNSFilter Dashboard. This will allow administrators to group users into Collections and apply specific policies, schedules, and block pages to those Collections or on a per-user basis.

Deploying the Windows Active Directory Sync Tool

Our Microsoft Windows Active Directory Sync Tool allows you to synchronize users from one or more Active Directory domains and forests in your environment. The Sync Tool allows you to synchronize the following items:

• Users: Manually select specific Active Directory Users which you’d like to sync
• Groups: Manually select specific Active Directory Groups which you’d like to sync.

These users and groups can be added to various DNSFilter Collections to apply specific policies and block pages to those users or groups of users. You may also apply specific policies and block pages on a per-user basis using the DNSFilter Users feature.

Please note: The sync tool for on-prem AD environments will not sync security groups. This can only be accomplished through Azure Active Directory environments.

To set up and configure the Microsoft Windows Active Directory Sync Tool, you may follow these instructions:

1. Navigate to Deployments > Sync Tools.
2. Click the Install Your First Sync Tool button.
3. Provide a Name for the new sync tool and click the Continue button.
4. NOTE: The Secret Key value is only accessible on the newly created Sync Tool page. Store this in a safe location in case you need to reinstall the sync tool in the future.
   • Please ensure that you are using the Secret Key value and not the Secret ID, as this will trigger an error in the sync tool configurator.
   • We would recommend making note of this value after it has been created so that it can later be referenced and added to your configuration. 
5. Download the Active Directory Sync Tool and install it on a domain-joined computer in your environment (we recommend against installing it on a Domain Controller, if possible).
6. Open the DNSFilter AD Sync Tool from the Start Menu and add the Secret Key value supplied in step #4 above. You may also change the default frequency so that the sync tool synchronizes any changes to your directory to DNSFilter.
7. For each Active Directory Domain that you wish to synchronize from, add a new entry to the Server List (on the AD server settings tab) and provide the following details:

• Friendly Name: Text which appears for this entry in the Server List
• Address: Fully-qualified hostname or IP address of the Domain Controller the sync tool should poll.
• Protocol: By default, the sync tool will use LDAPS (TLS/SSL) over port 636. You may optionally change this to non-secure LDAP over port 389.
• Username and Password: If the sync tool is installed on a non-domain computer, provide the credentials for a service account with at least Domain User permissions.

8. Press the Test button to confirm your settings are valid, then press the Load button to verify proper connectivity to Active Directory. If connectivity is successful, a list of Active Directory Organizational Units (OUs) will be displayed. Expanding each of those OUs will show Groups and Users within those OUs. If you run into the error message below after testing the connection, then we would recommend unchecking the TLS/SSL option, as your server may not support those capabilities.
   
9. Optionally limit which OUs, Groups, and/or Users you wish to sync to DNSFilter. By checking all options, the sync tool will synchronize all groups and users. Some administrators may wish to limit the synchronization so that administrator accounts, service accounts, etc., do not get synchronized.
10. Press the Save button to save the selected OUs, Groups, and/or Users you selected in the previous step and to force the initial synchronization to occur. The initial synchronization may take a few minutes to complete. After the synchronization is complete, you will see synchronized groups and users within your DNSFilter Dashboard.

Please Note: The AD Sync Tool does require the Active Directory Recycle Bin feature to be enabled to allow you to remove synced users from the DNSFilter Dashboard if they have been deleted in your Active Directory. This feature allows for better management of your Active Directory in general and is recommended to turn on. More documentation from Microsoft on this feature can be found here. Not using this feature is optional, but your ability to remove synced users will not be available without it.

The DNSFilter Microsoft Windows Active Directory Sync Tool runs as a system service to ensure it automatically starts if the computer is rebooted. It’s important to install the sync tool on a computer that doesn’t get shut down and has a stable internet connection.

Azure Supported

Our Microsoft Windows Active Directory Sync Tool also works with Azure Active Directory and allows you to synchronize users from one or more Azure Active Directory subscriptions.

Users and groups can be added to various DNSFilter Collections to apply specific policies and block pages to those users or groups of users. You may also apply specific policies and block pages on a per-user basis using the DNSFilter Users feature.

To set up and configure Azure Active Directory, follow these instructions:

1. Set up a new Azure application making sure to select the Microsoft graph API permissions of Group.Read.All, GroupMember.Read.All and User.Read.All. Then click the button to "Grant admin consent" for your directory.
   
   Please Note: You will want to ensure that the Type is set to Application and not Delegation as this will lead to a connection error in step #2
   
2. Copy the Tenant ID, Client ID, and Client Secret from your Azure Active Directory instance, add them to the Azure tenant settings tab of the Microsoft Windows Active Directory Sync Tool, and make sure the settings are saved.
3. Select the groups / OUs that need to be synced

Logging and Progress Bar

A progress bar at the top shows how far along the sync is. A sync, especially a first one, can take a long time, and this bar should alleviate concerns that the process is timing out.

The Last Sync Status will also display additional details outlining status, objects synced, and duration.

If a failure is encountered during a sync, you can view the errors for a specific server.

• Tab called Sync Logs [1]
  • Filtering [2]
    • Customers can filter by full log, errors only, and errors and warnings only
  • Refresh Logs [3]
    • When this button is engaged, it will reload with the most current logs.
  • open folder with logs  [4]
    • When this button is engaged, it will open window explorer with the file where logs exist on the customer's local machine.
  • Different viewing modes with navigation [5]
    • dual page
    • single page
  • Free text Search [6]
  •  Log Zoom [7]

Automatic Full Sync

Currently, in the Sync tool settings tab, customers can configure a customized frequency for an incremental sync to run. If customers do not select a frequency, it will default to 30 minutes, which is also the minimum. The incremental sync ensures any newly created users and groups in the on-prem AD or Azure AD are synced directly to the DNSFilter app. The incremental sync will run based on the frequency the customer determines, looking for these updates.

With this release, there will now be a full sync which occurs in the background every 3 to 6 days. The full sync will push all changes, including the scenario above, and does not require any action from the customer. This solves an issue that incremental sync did not support, which was when a user switched groups. For example, if Jhon Holland is assigned to the AI Group in AD, Jhon will then sync to the AI Collection in the DNSFilter app during an incremental sync. However, if Jhon moves from the AI to the Users Abroad Group in AD, the incremental sync would not reflect this change.

To force a full sync: Remove the sync tool cache inside the install folder. The file is named “AdSyncCookies.dat.” Delete this file, and then restart the service.

Please note that users that are removed from the AD premise environment or Azure AD are not synced with our dashboard where users are going to be removed.

Enabling Logging

In the event you experience issues with the Sync tool, it has Debug Logging capability!

in the ADSync install directory, there is a file called  Log4Net.config - It needs to be edited in two places:
<level value="INFO"/>  needs to change to <level value="DEBUG"/>
and
<file value=""/>  needs to change to a location and file that can be written.
For example <file value="C:\temp\ads-debug.log"/>

Once you've made these edits, the AD Sync service needs to be stopped and restarted, and the log file will start populating.

This can be sent to support with your ticket for further troubleshooting and review.

AD Sync Tool Version Log

You can find the history of the Active Directory integration release notes on our public changelog.