Active Directory Integration (ADI) Configuration Guide – IV Test Sandbox

You can use KnowBe4's Active Directory Integration (ADI) feature to integrate your organization's Active Directory (AD) with your KSAT console. After you configure ADI, users and groups will be automatically added, changed, and archived in your KSAT console based on information sent from your AD. It's important to note that this is a one-way process of synchronization, and no information will be sent back to your AD from your KSAT console.

To learn about the benefits of configuring ADI for your organization, see our Benefits of Setting Up Active Directory Integration (ADI) article. If you prefer video tutorials to learn how to configure ADI, see our Active Directory Integration (ADI) video. Alternatively, if you are interested in using SCIM to sync your users, please check out our SCIM Configuration Guide.

Note:Depending on your organization's environment, you may need to use advanced configuration options. For more information about advanced configuration options, see our Active Directory Integration (ADI) Advanced Configuration Guide.

How ADI Operates for Accounts with Existing Users

If you've already added users to your KSAT console, there are a few things you should know before configuring ADI. For more information, see the list below:

Once you've configured ADI, the data that is synced from your AD is considered authoritative. The following actions will occur during syncs between your KSAT console and your AD:
- Users who are not found in your AD will be archived in your KSAT console.
- If you've made changes to a user's information in your KSAT console, these changes will be overwritten by the data that is contained in your AD.
Prior to ADI, user accounts in the KSAT console are considered console-managed. When users are console-managed, you can edit user information by uploading a CSV file to your console or by editing user profiles directly in your console.
- Once you configure ADI and the first AD sync occurs, users are considered AD-managed. When users are AD-managed, you will need to edit user information in your AD and these changes are then pushed to the KSAT console during the next sync.
During the first AD sync, the KSAT console will automatically match console-managed user accounts with accounts in your AD. This process will convert your users from being console-managed to AD-managed. We've outlined how this process works below:
1. You will install and configure the ADI sync tool in your environment. For details, see the Installation and Configuration section of this article.
2. You will configure what information you want to sync from your AD. For details, see the Defining Which OUs, Groups, and Users to Sync section of this article.
3. Then, the ADI sync service queries your AD or directories for user and group information and sends the results to KnowBe4's servers.
4. KnowBe4's servers review the information sent from your AD and the servers automatically update the users and groups in your KSAT console according to the following logic:
  If an AD user has an email address that matches an existing KSAT console account, then that KSAT console user account becomes AD-managed.
  
  If an AD user is not found in the KSAT console, then an AD-managed user account is created.
  
  After all AD users have been processed, any console accounts that have not become AD-managed will be archived.

Once you configure ADI, user information will stay up-to-date with the information in your organization's AD.

Prerequisites

Before you configure ADI, make sure that your environment meets our basic requirements listed below:

Your organization must have Microsoft Active Directory or Microsoft Entra ID. See the list below for more information:
1. If your organization has Microsoft Active Directory, your domain functional level must be Windows Server 2016 or later.
2. If your organization has Microsoft Entra ID, you can sync Microsoft Entra ID Domain Services with your KSAT console. To learn more, see our How to Use Active Directory Integration with Microsoft Entra ID Domain Services article.
We recommend that you install the ADI tool on an application server and not a user workstation. Make sure that the system where you will install ADI meets the following specifications:
1. The system uses Windows Desktop 10 11; or Windows Server 2016/2019 or 2022 (64 bit).
2. Make sure that the system can reach the server of the training instance for your account. For a list of instances, see our KnowBe4's Training Instances article. The training instance is the server URL that KnowBe4's AD sync tool will need to contact through a POST request. You will need to allow outbound connections to remote servers on port 443 (SSL/HTTPS).
3. The computer has at least two GB of RAM.
4. The computer's system drive has at least one GB of available hard disk drive (HDD) space.
5. User Account Control (UAC) is enabled in the computer's User Account Control settings.

Note:If you are configuring ADI through a proxy, you will need to add an HTTP_PROXY variable to your Environment Variables. For more information, see our Configure the ADI Sync Tool to Connect Through a Proxy article.

See the next section for important steps you will need to take to prepare for your ADI configuration.

Before You Begin: Required Steps

Before you can install and configure KnowBe4's AD sync tool on your local system, follow the steps below:

Gather the following information about your AD:

Important:If your users are located under more than one domain controller, you will need to gather the following information for each domain controller. You will also need to configure ADI for each of these domains. To learn more, see the Multiple Source Domain Support section of our Active Directory Integration (ADI) Advanced Configuration Guide.
- Find the IP address or Fully Qualified Domain Name (FQDN) for the domain controller where your AD is located.
- Make sure that your AD domain controller can respond to LDAP requests. By default, all domain controllers are set up to respond to LDAP requests.
  
  Tip:Your AD sync can communicate over LDAP. However, if you would rather, you can enable LDAPS on your domain controller before syncing your AD. By default, LDAPS is not enabled on most domain controllers. To learn more, see our ADI FAQ.
- Find the AD domain name. The AD domain name is the root domain that is controlled by your AD domain controller. See the image below for an example of an AD domain name.
- Make sure that you have the username and password for an AD administrator account that has the permissions to perform LDAP queries. By default, any account in the "Domain Users" group has these permissions. However, for additional security, we recommend using a service account that only has “read” permissions for your AD. To see the "read" permissions that are necessary for this service account, please see our Active Directory Integration (ADI) Advanced Configuration Guide.
Obtain your ADI Sync Token and download the ADI sync tool from your KSAT Account Settings. Follow the steps below:
1. Once you're logged in to your KSAT console, click your email address in the top-right corner of the page. Then, click Account Settings.
2. Navigate to the User Provisioning section. Then select the Enable User Provisioning (User Syncing) check box.
3. Make sure that the Test Mode setting is enabled. Test Mode should only be turned off after you have completed your ADI setup and you have verified that ADI is operating correctly. While Test Mode is enabled, user provisioning or syncing does not occur. Instead, a report is generated to show what would have happened if the user provisioning took place. Test Mode allows you to resolve any potential issues without affecting the current users that you have in your console.
  
  Tip: Selecting the Show Group Domain check box can be a helpful feature if your users are split between multiple domain sources. To learn more, see our ADI FAQ.
4. Copy your ADI Sync Token and save it locally. You will need this token to complete your setup. Your ADI Sync Token is 34 digits in length and looks similar to the following example: US9X140X4829E37XX545401X97912X604X.
5. Click the download icon next to ADI Tool (ADISyncSetup.exe) to download the file for the ADI tool.
6. Click the Save Changes button at the bottom of the Account Settings page.
7. Decide which users you want to synchronize, and become familiar with where these user objects are located in your AD.
After you complete the steps in this section and the steps in the Installation and Configuration section below, you will need to define where the user objects are located in your AD. You can sync user objects from one or more of the following: organization units (OUs), security groups, and distribution groups. To see additional details about defining the users that you want to sync, see the Defining Which OUs, Groups, and Users to Sync section of this article.
If you find that your user objects are not located in OUs, security groups, or distribution groups, see the information below:
- If the users that you would like to sync are located in the built-in users container instead of an OU: You cannot sync containers. As a workaround, you can create a security group, add those users to the security group, and then sync that group instead of the container.
- If you find that your AD is not organized in an ideal way for syncing with the KSAT console or if you are unsure: You can set up one or more groups in AD for the purpose of containing all of the user objects and groups you'd like to sync. Then, you will specify that you want to sync only those groups.
- If you have a root domain with child ADs, you can run the ADI installer for each child domain. Each child domain must use the same domain controller as the root domain.
Determine which field your users' email addresses should be pulled from in AD. By default, the ADI service will pull your users' proxy addresses to use as their KnowBe4 account email addresses.
- If you need to use something other than proxy addresses, you will need to edit the emailAttrib field in your adisync.conf file. For example, if you are not using Microsoft Exchange or Microsoft 365 as your mail server, your proxy address field in AD is most likely blank. Edit the emailAttrib field after you perform the installation but before you start the ADI sync service. For instructions, see the Changing Where to Pull Email Addresses from in Active Directory section of our Active Directory Integration (ADI) Advanced Configuration Guide.
  
  Note: The useMailAttrib field has been replaced with the emailAttribute field.
- Make sure all campaigns have their settings properly adjusted for the influx of users. Double-check your Smart Groups settings in campaigns as they can be affected by new users appearing through ADI sync.

Once you have gathered the information above, continue with the steps in the next section.

Installation and Configuration

Once you have gathered the information outlined in the section above, you are ready to install and configure your ADI sync. Continue with the steps below:

Run the Active Directory sync tool. This is the ADISyncSetup.exe file that you downloaded from your KSAT Account Settings in step 2 of the Before You Begin: Required Steps section above. The AD sync tool does not need to be installed on a domain controller. It can be installed anywhere in the environment as long as the system can communicate with a domain controller that accepts LDAP connections.

Tip:Your AD sync can communicate over LDAP. However, if you would rather, you can enable LDAPS on your domain controller before syncing your Active Directory. By default, LDAPS is not enabled on most domain controllers. To learn more, see our FAQ: Active Directory Integration (ADI) article.

A command prompt will automatically open to the installation directory. The following is the default location of the installation directory on 64-bit platforms: C:\Program Files \KnowBe4\ADI Sync
In the command prompt window, you will be prompted to enter the information outlined below:
1. Enter your 34 character ADI Sync Token: If this is the first time you are running this command, you will be prompted to enter your Active Directory Synchronization Token. This token is the string of characters that you copied from your KSAT Account Settings. For more information, see step 2 in the Before You Begin: Required Steps section above.
2. Enter Active Directory domain name: The domain name refers to the root domain for your AD. For an example, see the Before You Begin: Required Steps section above.
3. Enter Active Directory domain controller hostname or IP address: The AD's hostname or IP address refers to the IP address or Fully Qualified Domain Name (FQDN) for your domain controller where your AD is located.
4. Enable SSL (true/false): By default, LDAPS is not enabled on your domain controller and you will type "false", or press the Enter key on your keyboard to automatically select false. Alternatively, if you have enabled LDAPS for the purpose of this sync, type "true" instead.
5. Enable SecurityCoach Fields (true/false): If you've purchased SecurityCoach, enter "true" to enable SecurityCoach fields. These fields will allow you to sync information for user mapping. For more information, see the Security Coach Fields section of our How to Edit Your CONF File for Active Directory Integration (ADI) article. By default, these fields are disabled. To keep these fields disabled, press Enter on your keyboard.
6. Enter Active Directory Port number [389]: Enter the appropriate LDAP or LDAPS port. By default, for LDAP the port is port 389 and for LDAPS the port is port 636.
7. Enter Username (user@domain): Enter the username for the AD administrator account that has the necessary read permissions to perform LDAP queries. This username should be in the format of "user@domain".
8. Enter Password: Enter the password for the AD administrator account that has the necessary read permissions to perform LDAP queries.
If the connection was successful, you will see a confirmation message that the ADI has been connected and configured for your domain, as shown in the example above.
Press the Enter key on your keyboard to exit the command prompt window.
If there were issues reaching or authenticating with your domain controller, you will see error messages in the command prompt window and you will need to repeat the steps in this section with the correct configuration data. If you continue to experience errors, please contact our support team.

Once your connection is successful, see the next section so you can specify the users and information that you want to sync with your KSAT console.

Defining Which OUs, Groups, and Users to Sync

After you have completed the steps in the previous two sections, you will edit the <your domain here>.conf file to configure the information that you want to sync with your KSAT account. This configuration is required to sync users from your AD.

Tip:When you are configuring the your domain here.conf file, it is helpful to have Active Directory Users and Computers (ADUC) open so the OU paths and groups are available to you.

Continue your ADI setup with the steps below:

Make sure that you have edit permissions on the C:\ProgramData\KnowBe4\ADI Sync\Config folder.
Find the <your domain here>.conf file in the installation directory, as shown below. Open the file in a text editor, such as Notepad.
The <your domain here>.conf file is used to define the users, user information, and groups that you want to sync between your KSAT account and your AD. To see an example of this file, open this sample_domain file.

Note: Make sure that you are editing the <your domain here>.conf file and not the adisync.conf file.
Edit the <your domain here>.conf file to specify the criteria for your user and group synchronization. There are three sections of the <your domain here>.conf file that you can modify:
- [sync.fields] (Optional): Edit this area to specify the user information fields that you want to sync from your AD. To learn more, see the Syncing Other User Information to KnowBe4 section of our How to Sync Information Through Active Directory article.
- [sync.users] (Required): Edit this area to specify which users you want to sync from your AD. Make sure you include at least one OU, group, or user under the [sync.users] section of the .conf file. To learn more, see the Sync Users by Inclusion/Exclusion of OU, Group, or Specific User (Required) section of our How to Sync Information Through Active Directory article.
- [sync.groups] (Optional): You can use this area to specify the groups that you would like to sync from your AD. These groups will be automatically created in your KnowBe4 console, and the applicable users will be added to the groups. To learn more, see the Sync Groups by Inclusion/Exclusion of OU or Group (Optional) section of our How to Sync Information Through Active Directory article.
Note:If your OUs or Group names contain letters that are not part of the standard English alphabet, replace the quotation marks (") with single quotes (') in the <your domain here>.conf file. Additionally, you will need to use a double backslash to escape special characters like commas, hashtags, and plus signs. For details, see our How to Use Escape Characters with Active Directory Integration article.
Once you're finished, save the changes you've made to the <your domain here>.conf file.

See the next section to start your ADI sync.

Start Your ADI Sync

If you have completed all of the steps above, your ADI service is now configured and you can start the ADI sync. Continue with the steps below:

Important:Before starting your sync, make sure that Test Mode is enabled in your KSAT Account Settings. For more information, see step 2 in the Before You Begin: Required Steps section above.

You may start the sync by using the Windows Service Control Manager to start the KnowBe4 ADI Sync Service.

The KnowBe4 ADI Sync Service will run immediately. While services are connected, syncs between your AD and the KSAT console will occur once every six hours.

When Test Mode is enabled in your Account Settings, you will see a preview of how your AD will sync to KnowBe4. To view the Test Mode preview, navigate to Users > Provisioning in your KSAT console.

Keep Test Mode enabled until you are sure that you have set up ADI in a way that meets your organization's needs. Once you're happy with your ADI setup, navigate to your KSAT Account Settings and disable Test Mode. Your next ADI sync will provision your users automatically.