In this article

Review this guide to install the DNSFilter Sync Tool, a built-in feature that integrates DNSFilter with Windows or Azure Active Directory (AD). Once installed, review the Sync Tool navigation guide to get familiar with the tool features. 

The Sync Tool feature allows network administrators to synchronize users to the DNSFilter Dashboard, grouping users into Collections and applying specific filtering policies, schedules, and block pages to those Collections or on a per-user basis.

In order to leverage this functionality, the DNSFilter Roaming Client must be installed on end-users' devices, which can be easily achieved via GPO push. 

Windows AD Sync Tool installation

The Microsoft Windows Active Directory Sync Tool syncs users from one or more AD domains and forests in the organization's environment.

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

We recommend a domain-joined computer in the organization's environment, not a domain controller, if possible. 

Follow these steps to complete the Sync Tool installation. 

Step one: Download the Sync Tool

1. From the DNSFilter dashboard, navigate to Deployments and select Sync Tools
2. Select Install Your First Sync Tool
3. Enter a Name for the new sync tool and select Continue
4. Copy the Secret Key. Store it in a secure location in case the sync tool ever needs reinstalled
   
   ✍️ Do not confuse the DNSFilter app secret key with the AD secret ID: entering the wrong value during the installation will return an error in the configurator
5. Download the Active Directory Sync Tool
6. Navigate to the Start Menu to open the Sync Tool
7. Add the Secret Key
8. (Optional) Update the default sync frequency if the initial sync fails to complete in the default timeframe

The Windows AD Sync Tool is now ready to configure. 

Step two: Configure the Sync Tool

1. From the Sync Tool, tab to AD Server Settings 
2. Add a new entry for each AD domain to sync from:
   1. Friendly Name: Name to appear in the Server List
   2. Address: Fully-qualified hostname or IP address of the domain controller the sync tool should pull
   3. 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
   4. 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
3. Select Test to confirm the settings are valid
   
   ✍️ If the test returns a user name or password error message, uncheck the TLS/SSL option, as the server may not support those capabilities
4. Select Load to verify the connection to AD is successful

If connectivity is successful, a list of AD Organizational Units (OUs) will be displayed. Expanding each of those OUs will show Groups and Users within those OUs. 

Step three: Complete the AD to DNSFilter Sync

1. Review the OUs, Groups, and Users displayed in the Sync Tool to confirm all should sync with the DNSFilter dashboard
   1. By checking all options, the Sync Tool will synchronize all groups and users
   2. Uncheck any entries that should not sync, for example some admins may wish to limit the synchronization to exclude administrator accounts, service accounts, etc. from the sync
2. Select Save to save the selected entries and force the initial sync, which may take a few minutes to complete. 

The sync groups and users will populate in the DNSFilter dashboard after the initial sync is complete. Navigate to the Collections page in the app dashboard to manage settings.  

Azure AD Sync Tool installation

The Sync Tool also works with Azure Active Directory, syncing users from one or more Azure Active Directory subscriptions.

Follow these steps to setup the Sync Tool with Azure AD. 

Step one: Download the Sync Tool

1. From the DNSFilter dashboard, navigate to Deployments and select Sync Tools
2. Select Install Your First Sync Tool
3. Enter a Name for the new sync tool and select Continue
4. Copy the Secret Key. Store it in a secure location in case the sync tool ever needs reinstalled
   
   ✍️ Do not confuse the DNSFilter app secret key with the AD secret ID: entering the wrong value during the installation will return an error in the configurator
5. Download the Active Directory Sync Tool
6. Navigate to the Start Menu to open the Sync Tool
7. Add the Secret Key
8. (Optional) Update the default sync frequency if the initial sync fails to complete in the default timeframe

Step two: Create a new Azure application

1. Create a new app following Microsoft's documentation
2. From the API Permissions, select Grant admin consent for these Microsoft Graphs:
   
   - Group.Read.All
   - GroupMember.Read.All
   - User.Read.All
3. Confirm the graph Type is Application to avoid configuration errors
   
   
4. Copy these fields to add to the Sync Tool:
   
   - Tenant ID
   - Client ID
   - Client Secret

Step three: Configure the Sync Tool

1. From the Sync Tool, tab to Azure tenant settings
2. Update the Tenant Information:
   1. Friendly Name: Name to appear in the Server List
   2. Tenant ID: Copied from Step two
   3. Client ID: Copied from Step two
   4. Client Secret: Copied from Step two
3. Select Test to confirm the settings are valid
   
   ✍️ If the test returns a user name or password error message, uncheck the TLS/SSL option, as the server may not support those capabilities
4. Select Load to verify the connection to AD is successful

Step four: Complete the AD to DNSFilter Sync

1. Review the OUs, Groups, and Users displayed in the Tenant Group List to confirm all should sync with the DNSFilter dashboard
   1. By checking all options, the Sync Tool will synchronize all groups and users
   2. Uncheck any entries that should not sync, for example some admins may wish to limit the synchronization to exclude administrator accounts, service accounts, etc. from the sync
      
      ✍️ If an "All Groups" group is configured, and within this group there are several groups listed, the Sync Tool is unable to identify these "nested" groups. Rather than a "nested" group, these need to be an OU tree down to the group/user object.
2. Select Save to save the selected entries and force the initial sync, which may take a few minutes to complete. 

The sync groups and users will populate in the DNSFilter dashboard after the initial sync is complete. Navigate to the Collections page in the app dashboard to manage settings.