Configuring Active Directory Integration

You can use KnowBe4's Active Directory Integration (ADI) feature to integrate your organization's Active Directory (AD) with your KMSAT console. After you configure ADI, users and groups will be automatically added, changed, and archived in your KMSAT 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 KMSAT 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.

Jump to:

How ADI Operates for Accounts with Existing Users

Prerequisites
Before You Begin: Required Steps
Installation and Configuration
Defining Which OUs, Groups, and Users to Sync
Start Your ADI Sync

How ADI Operates for Accounts with Existing Users

If you've already added users to your KMSAT 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 KMSAT console and your AD:
  • Users who are not found in your AD will be archived in your KMSAT console.
  • If you've made changes to a user's information in your KMSAT console, these changes will be overwritten by the data that is contained in your AD.
• Prior to ADI, user accounts in the KMSAT 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 KMSAT console during the next sync.
• During the first AD sync, the KMSAT 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 KMSAT console according to the following logic:
     
     • If an AD user has an email address that matches an existing KMSAT console account, then that KMSAT console user account becomes AD-managed.
     • If an AD user is not found in the KMSAT 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.

Back to top

Prerequisites

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

1. Your organization must have Microsoft Active Directory or Azure Active Directory. See the list below for more information:

• If your organization has Microsoft Active Directory, your domain functional level must be Windows Server 2003 or later.
• If your organization has Azure Active Directory, you can sync Azure Active Directory Domain Services with your KMSAT console. To learn more, see our How to Use Active Directory Integration with Azure Active Directory Domain Services article.

2. 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:

• The system uses Windows Desktop 10 or Windows Server 2016/2019/2022 (64 bit).
• 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).

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

Back to top

Before You Begin: Required Steps

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

1. Gather the following information about your AD:

• 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.

2. Obtain your ADI Sync Token and download the ADI sync tool from your KMSAT Account Settings. Follow the steps below:

1. 1. Once you're logged in to your KMSAT 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 32 digits in length and looks similar to the following example: 9X140X4829E37XX545401X97912X604X.
   5. Click the download icon next to ADI Tool (KnowBe4_AD_Sync.msi) 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. 

3. 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 KMSAT 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.

4. 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.

Back to top

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:

1. Run the Active Directory sync tool. This is the KnowBe4_AD_Sync.msi file that you downloaded from your KMSAT 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.

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 (x86)\KnowBe4\ADISync

2. In the command prompt window, you will be prompted to enter the information outlined below:

1. 1. Enter Active Directory Synchronization 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 KMSAT Account Settings. For more information, see step 2 in the Before You Begin: Required Steps section above.
   2. Enter 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 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: 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: 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.

3. If the connection was successful, you will see confirmation messages in the command prompt window, as shown in the example below. 

4. 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 KMSAT console.

Back to top

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 KMSAT account. This configuration is required to sync users from your AD.

Continue your ADI setup with the steps below:

1. Make sure that you have edit permissions on the ADISync folder. 

2. 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 KMSAT account and your AD. To see an example of this file, open this sample_domain file.

3. 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.

4. 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.

Back to top

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:

You may start the sync in one of two ways:

1. Use the Windows Service Control Manager (the ADI service is called "Active Directory Integration Sync Service"), or
2. Open a command prompt in administrator mode and then follow the two steps below:
   1. Navigate to the appropriate directory. The following is the default location of the installation directory on 64-bit platforms: C:\Program Files (x86)\KnowBe4\ADISync
   2. Type ADIsync.exe service start and press the Enter key on your keyboard.

The ADI sync service will run immediately and while services are connected, syncs between your AD and the KMSAT 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 KMSAT 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 KMSAT Account Settings and disable Test Mode. Your next ADI sync will provision your users automatically.

Back to top