Configuring Active Directory Integration

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

We also have a video that shows how to set up Active Directory Integration. However, we recommend that you read through the sections below for a more detailed understanding of how ADI works.

Jump to:

What Are the Benefits of Setting up ADI?
How ADI Operates for Accounts With Existing Users
Prerequisites
Before You Begin: Required Steps
Installation & Configuration
Defining Which OUs, Groups, and Users to Sync
Start Your Synchronization
Advanced Configuration Options

• Multiple Source Domain Support
• How Do I Change Where to Pull the Email Addresses from Active Directory?
• How Do I Sync Custom Fields?

How Do I Install the Newest Version of ADI?

What Are the Benefits of Setting up ADI?

Integrating KnowBe4 with your Active Directory (AD) allows you to add your users and groups from your AD to your console and makes the process of managing your users and groups easier.

Click the drop-down menus below to learn more about the benefits of integrating your AD with KnowBe4.

Back to Top

How ADI Operates for Accounts With Existing Users

If you've already added users to your KnowBe4 account, there are a few things you should know before configuring your Active Directory Integration (ADI). See the list below:

• Once you've configured ADI, the data that is synced from your Active Directory is considered authoritative. The following actions will occur during syncs between the KnowBe4 console and your AD:
  • Users who are not found in your Active Directory will be archived in your KnowBe4 console.
  • If you've made changes to a user's information in the KnowBe4 console, these changes will be overwritten by the data that is contained in your Active Directory.
• Prior to ADI, user accounts in the KnowBe4 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 Active Directory and these changes are then pushed to the KnowBe4 console during the next sync.
• During the first AD sync, the 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.
  2. You will configure what information you want to sync from your Active Directory. 
     • For details, see the Defining Which OUs, Groups, and Users to Sync section below.
  3. Then, the ADI sync service queries your Active Directory or Directories for user and group information and sends the results to the KnowBe4 servers.
  4. The KnowBe4 servers review the information sent from your AD and the servers automatically update the users and groups in your KnowBe4 console according to the following logic:
     
     • If an AD user has an email address that matches an existing KnowBe4 console account, then that KnowBe4 console user account becomes AD-managed.
     • If an AD user is not found in the KnowBe4 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 your Active Directory Integration (ADI), user information will stay up-to-date with the information in your organization's Active Directory.

Back to Top

Prerequisites

Before you begin setting up ADI, ensure that your environment meets our basic requirements. See the details outlined below. 

1. Your organization must have one of the following Active Directory services:
   • Microsoft Active Directory: Your domain functional level must be Windows Server 2003 or later.
   • Azure Active Directory: You can sync Azure Active Directory Domain Services with the KnowBe4 console. To learn more, see: How to Use Active Directory Integration with Azure Active Directory Domain Services.
2. We recommend that you install the ADI tool on an application server and not a user workstation. Ensure that the system where you will install ADI meets the following specifications:
   • Windows Desktop 7/Vista/8/10 or Windows Server 2008/2012/2016/2019 (64 bit).
   • Ensure this system can reach one of the following servers, depending on where your KnowBe4 account is located:
     • https://training.knowbe4.com
     • https://eu.knowbe4.com
     This 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 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, you must follow the steps below to prepare for this configuration.

1. You will need to gather the following information about your Active Directory (AD) to configure ADI. Follow the steps below: 
   

   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 below.
   1. Find the IP address or Fully Qualified Domain Name (FQDN) for the domain controller where your Active Directory is located.
   2. Ensure 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 Active Directory. By default, LDAPS is not enabled on most domain controllers. To learn more, see our FAQ: I want to set up LDAPS.
   3. 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:
      
   4. Ensure 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: How to create an ADI Service Account in Active Directory. 
2. Obtain your ADI Sync Token and download the ADI sync tool from your KnowBe4 Account Settings. Follow the steps below:
   1. Once you're logged in to your KnowBe4 account, click your email address in the top right-hand corner. Then, click Account Settings.
   2. Navigate to the User Provisioning section. Then click the Enable User Provisioning (User Syncing) checkbox, as shown below.
      
   3. Ensure the Test Mode setting is enabled, as shown below. 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:

      Enabling the Show Group Domain checkbox can be a helpful feature if your users are split between multiple domain sources. To learn more, see: What does enabling the Show Group Domain option in my Account Settings do?
   4. ADI Sync Token: Copy your ADI synchronization 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 this: 9X140X4829E37XX545401X97912X604X.
   5. Download the ADI Tool: Click the download icon next to ADI Tool (KnowBe4_AD_Sync.msi) to download the file. 
   6. Click the Save Changes button at the bottom of the Account Settings page.
3. 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 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: Defining Which OUs, Groups, and Users to Sync.
   If you find that your user objects are not located in OUs, security groups, or distribution groups, see the information below:
   
   • If the users you'd 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 KnowBe4 console or you are unsure: You can set up one or more groups in Active Directory 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.
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. 
   • 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 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: How Do I Change Where to Pull the Email Addresses from Active Directory?
     

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:

5. Run the Active Directory sync tool. This is the KnowBe4_AD_Sync.msi file that you downloaded from your console's Account Settings (see step 2 in the Before You Begin 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: I want to set up LDAPS.
6. 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
7. In the command prompt window, you will be prompted to enter the information outlined below:
   1. 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 KnowBe4 Account Settings (see step 2 in the Before You Begin section above).
   2. Enter Domain Name: The domain name refers to the root domain for your AD. For an example, see this step under the Before You Begin 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 Active Directory is located.
   4. Enable SSL (true/false): By default, LDAPS is not enabled on your domain controller and you will type false, or press Enter on your keyboard to automatically select false. Alternatively, if you have enabled LDAPS for the purpose of this sync, type true instead.
   5. 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.
   6. 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".
   7. Enter Password: Enter the password for the AD administrator user account.
8. If the connection was successful you will see confirmation messages in the command prompt window, as shown in the example below. 
   
9. Press Enter 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 KnowBe4 account.

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 KnowBe4. This configuration is required to sync users from your Active Directory.

Continue your ADI setup with the steps below:

11. Ensure you have edit permissions on the ADISync folder. 
12. 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 KnowBe4 and your Active Directory. To see an example of this file, open this sample_domain file.
      

      Note:

      Ensure that you are editing the <your domain here>.conf file and not the ADISync.conf file.
13. 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 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: Syncing Other User Information to KnowBe4.
    • [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: Sync Users by Inclusion/Exclusion of OU, Group, or Specific User (Required).
    • [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: Sync Groups by Inclusion/Exclusion of OU or Group (Optional).

    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 How to Use Escape Characters with Active Directory Integration.
14. 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 Synchronization

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:

15. 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 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 Enter on your keyboard.

The ADI sync service will run immediately and while services are connected, syncs between your AD and the KnowBe4 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, in your KnowBe4 console, click Users > Provisioning.

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 KnowBe4 account settings and disable Test Mode. Your next ADI sync will provision your users automatically.

Back to Top

Advanced Configuration Options

Depending on your organization's environment, you may need additional configurations. Read the sections below to see if these options apply to your organization: 

• Multiple Source Domain Support
• How Do I Change Where to Pull the Email Addresses from Active Directory?
• How Do I Sync Custom Fields?

Multiple Source Domain Support

If your users are split between multiple domain sources, you will need to set up a configuration for each domain that contains user objects that you need to synchronize. For each of your additional domains, you will need to rerun the ADIsync.exe config in the ADI sync installation directory. Rerunning the ADI sync configuration will create the additional <your domain here>.conf files that you will need to edit in order to specify the filter criteria for your sync. 

Follow the steps below to run ADI sync configuration again:

1. Open a command prompt in administrator mode.
2. Navigate to the \ADIsync system directory.
   • The system directory's default location on 64-bit platforms is: C:\Program Files (x86)\KnowBe4\ADISync
3. Type adisync.exe config and press Enter on your keyboard.
4. Enter the details for your additional domain controller and domain.
   • For details, see step 7 under the Installation and Configuration section above.  
5. Once the additional <your domain here>.conf file has been created, edit the file to specify the information that you would like to sync.
   • For details see: Defining Which OUs, Groups, and Users to Sync.
6. Save the <your domain here>.conf file. Once you've repeated this process for all of your additional domains, you can start your synchronization. 

Back to Top

How Do I Change Where to Pull the Email Addresses from Active Directory?

By default, ADI sync will sync all proxy email addresses for your users. However, you can change where you'd like to pull email addresses from in Active Directory. Additionally, you can choose to sync only the primary proxy email address of the user.

Open your ADISync.conf file from within C:\Program Files\KnowBe4\ADISync. By default, you will see the following fields:

• emailAttribute = "proxyAddresses"
• primaryproxyonly = false

See the details below to learn how to change what email addresses sync for your users. These fields are case-sensitive:

• Primary Proxy Only: If you'd like to use only the primary proxy address for each user, change the primaryproxyonly field from false to true. Then, save the ADIsync.conf file, and start the ADI service again. This will ensure that no alias email addresses are synced.
• Mail Attribute: If you'd like the sync to use the Mail attribute instead of proxyAddresses, change the emailAttribute field to "mail" instead of "proxyAddresses" and the useMailAttrib field to "true" instead of "false". Then, save the ADIsync.conf file and start the ADI service again.
  

  Note:

  Regardless of which field you are syncing by, the mail attribute for a user cannot be empty. For the purposes of ADI, this value does not need to be a valid domain. If your organization does not want to use the mail attribute, please contact support and they will be happy to assist you.

• User Principal Name: If you'd like the sync to use the userPrincipalName (UPN) instead of proxyAddresses, change the emailAttribute field from "proxyAddresses" to "userPrincipalName". Then, save the ADIsync.conf file and start the ADI service again.

Back to Top

How Do I Sync Custom Fields?

The user profiles in your KnowBe4 console include custom fields (click to view example) that you can use to sync additional information from your Active Directory. To specify the information that you want to sync to the custom fields, edit the <your domain here>.conf file and then start the service again for your changes to sync. To learn more, see Syncing Other User Information to KnowBe4.

Back to Top

How Do I Install the Newest Version of ADI?

You can install the newest version of ADI without uninstalling your previous version. Follow the steps below:

1. Download the new installer (the KnowBe4_AD_Sync.msi file) from your KnowBe4 account settings.
2. Run the installation.
3. Close the DOS prompt that appears at the close of installation.
4. Start the sync service.

Your users should continue to sync as expected.

Back to Top