Menu

Active Directory Integration (ADI) Configuration Guide

Avatar
Maddy Townsend
Updated
Follow

Configuring Active Directory Integration

The KnowBe4 Active Directory Integration (ADI) feature allows you to leverage Active Directory to populate and maintain your users and groups within your KnowBe4 Console. After you configure ADI, users and groups will be automatically added, changed, and archived 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.

Alternatively, if you are interested in using SCIM to sync your users, please check out our SCIM Configuration Guide.

We also have a video that shows how to set up Active Directory Integration. However, we recommend that you read through the sections below.

Jump to:
Benefits of ADI
How ADI Operates
Prerequisites: Before You Get Started
Installation & Configuration

Start Your Synchronization
Advanced Configuration Options

 

What Are the Benefits of Setting up ADI?

Using ADI makes it easy to keep your KnowBe4 user list up-to-date. If your users' information changes, new employees come on board, or anyone leaves your organization, once the relevant changes are made in Active Directory, those changes will automatically be carried over to your KnowBe4 console during the next sync.

You can set up campaigns that work with your integration to automate security awareness training for new employees. When ADI is set up, new users added to your Active Directory can automatically A) have an account created in your KnowBe4 console, B) begin to receive phishing emails, and C) be enrolled in a new employee training campaign. All in one single step of adding them to Active Directory.

Back to Top

 

How ADI Operates

If you're a brand new KnowBe4 customer and have not yet imported users, integrating your KnowBe4 console with Active Directory will allow you to import all the users you want to include in phishing and training campaigns all at once.

For existing customers, it is important to configure ADI so that current user account information is maintained during syncs. The synchronization of data from Active Directory is considered authoritative. This means that by default, any users who are not found in your Active Directory will be archived in your KnowBe4 console and any manual changes you've made to a user in the KnowBe4 console will be overwritten by the data contained in your Active Directory.

Prior to Active Directory Integration (ADI), all user accounts in the KnowBe4 Console were considered console-managed. This means changes are made in the console by either editing the users directly or updating them via CSV imports. Once ADI has been enabled and the sync occurs, users are considered to be AD-managed, meaning changes are all done at the Active Directory level and then, pushed to the console.

For existing customers with console-managed user accounts, an automatic process will match console-managed user accounts with user accounts in your Active Directory, making your account AD-managed. This process works as follows:

  • You install and configure the ADI Sync component at your site.
  • The ADI Sync service queries the Directory(s) for user and group information and sends the results to the KnowBe4 servers.
  • The KnowBe4 servers review the information sent and update the users and groups on the server according to the following logic:
    • For user email addresses, proxy addresses will be pulled by default. If you want to use something other than proxy addresses, you will need to change the ADIsync.conf file's emailAttrib setting to a different field name (such as "mail") after installation but prior to running the ADI sync service. For more information, see: How Do I Change Where to Pull the Email Addresses from Active Directory?
    • If an AD user has an email address that matches an existing KnowBe4 console account, then that 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.

Back to Top

 

Prerequisites

Before you begin setting up ADI, you'll need to gather some basic information by following the below steps:

  1. Confirm your setup meets our basic requirements:
    • You'll need an Active Directory.
    • Windows Desktop 7/Vista/8/10 or Windows Server 2008/2012/2016/2019 (64 bit). Also, ensure your PC (where ADI is installed) can reach https://training.knowbe4.com or  https://eu.knowbe4.com depending on where your KnowBe4 account is located  (Allow outbound connections to remote servers on port 443 (SSL/HTTPS)--that is the server URL ADI is trying to contact via a POST request). We recommend that you install the ADI tool on an application server and not a user's workstation.
    • If your mail server is not Exchange or Microsoft 365, click here for specific instructions to assist you with your sync.
    • If you're configuring ADI through a proxy, you'll also need to follow the instructions in this article.
  2. Make sure you have the following domain information ready:
    NOTE: If you have multiple domains with user objects for synchronization, you’ll want to have that information ready as well. See: Multiple Source Domain Support
    1. IP address or FQDN for an AD Directory Controller: By default, all Domain Controllers are set up to respond to LDAP requests.
    2. AD Domain Name: This is the root domain for your Active Directory, i.e., organization.com.
    3. Username/Password to query LDAP: An AD account that has the access rights to perform LDAP queries. By default, any account in the "Domain Users" group has sufficient permissions; however, for better security, we recommend using a service account that only has “read” permissions for your AD. See: How to create an ADI Service Account in Active Directory for the required “read” permissions for the service account.
  3. Obtain your ADI Sync Token and ADI Tool from your Account Settings. To do that, follow the below steps:
      1. Log in to your KnowBe4 console.
      2. Click your email address on the top right and then click on Account Settings.
      3. Under the User Provisioning section, enable the Enable User Provisioning option.
      4. Make sure to leave the Test Mode setting enabled. Test Mode should only be turned off after you have completed your ADI setup and verified that it is operating correctly.
        • While Test Mode is enabled, user provisioning or syncing does not occur. Instead, a report is generated which shows what would have happened if the user provisioning took place. This allows you to resolve any potential issues without affecting the current users you have in your console. 
      5. Click the ADI toggle to access your ADI settings.
      6. From your ADI settings, complete the following three steps:
        1. Copy your ADI synchronization token, located in the ADI Sync Token field, and save it locally - you'll need this to complete your setup.
          • Your ADI Sync Token is 32 digits in length and looks similar to this: 9X140X4829E37XX545401X97912X604X
        2. Download the ADI Tool. This is the .msi file in your Active Directory Integration Settings.
      7. Click Save Changes on the bottom of the Account Settings page.
  4. Know what users you want to synchronize:
    Part of the configuration requires knowing where in AD the user objects are. The configuration supports specifying a combination of organization units (OUs) and groups (security and distribution) to be queried for users. It's helpful to have Active Directory Users and Computers (ADUC) open when configuring the synchronization so that OU paths and groups are readily available.
    • If the users you'd like to sync are located in the built-in User container instead of an OU, you'll want to create a security group, add those users to it, and sync that group instead. (You cannot sync containers.)
    • If you find that your AD is not organized in an ideal way for syncing with the KnowBe4 console or are unsure, you can set up one or more groups in Active Directory for the purposes of containing all of the user objects and/or groups you'd like to sync, and then choose to sync ONLY those groups.
  5. Know that the ADI service will pull your users' proxy addresses as their KnowBe4 account email by default. If you want to use something other than proxy addresses, you will need to change the ADIsync.conf file's emailAttrib setting to a different field name (such as "mail") after installation but prior to running the ADI sync service. For more information, see: How Do I Change Where to Pull the Email Addresses from Active Directory?

Back to Top

 

Installation and Configuration

Once you've gathered all the information you need, you're ready to begin installing and configuring your ADI Sync.

  1. Run the Active Directory Sync Tool (the .msi file from your console's Account Settings). The AD sync tool may be installed anywhere in the environment as long as the system can communicate with a Domain Controller that accepts LDAP connections. The application does not need to be installed on a Domain Controller.

    Note:

    LDAPS is not enabled on most Domain Controllers. If you'd like to set up LDAPS, see our FAQ: I want to set up LDAPS.

  2. A command prompt will be opened and will navigate to the installation directory automatically:
    • C:\Program Files (x86)\KnowBe4\ADISync (default location on 64 bit platforms)
  3. You'll be prompted to enter the below information:
    • The first time this command is run, you will be prompted for the Active Directory Synchronization Token. This is the string from your Account Settings within your KnowBe4 console.
    • When prompted, enter the Domain Name of your Active Directory (see example below).
    • When prompted, enter the Domain Controller hostname (FQDN) or IP address.
    • When prompted, select if you’ve got LDAPS available. This is set to FALSE by default. If you do have LDAPS enabled, you can change that setting to TRUE if you wish.
    • When prompted, select the LDAP/LDAPS port--389/636 respectively is default.
    • When prompted, enter the username for LDAP. Use the format of "user@domain".
    • When prompted, enter the password for the supplied user.
    • Press Enter to Exit once all information has been added.

As long as the connection was successful, you will be returned to the command prompt with no errors. If there were issues reaching or authenticating, an error will be displayed and the above process will need to be done again with valid configuration data.

Back to Top

 

Defining Which OUs, Groups, and Users to Sync

After the above steps have been completed, you will need to configure the LDAP filter. This configuration is required in order to sync users from your Active Directory.

  1. Ensure you have edit permissions on the ADISync folder. 
  2. In a text editor, such as Notepad, open the <your domain here>.conf file located in the installation directory. This file is used to define everything you want to sync over from Active Directory. To see an example .conf file, open this sample_domain file.
  3. Specify the filter criteria for user and group synchronization. Make sure you include at least one OU, group, or user beneath the sync.users portion of the .conf file. 

    Note:

    If your OUs or Group names contain characters that are not part of the standard English alphabet, replace the quotation marks (") with single quotes ('). Escape special characters like commas, hashtags, and plus signs by using a double backslash. See this article for more information.

Follow the links below to learn more about syncing information to KnowBe4 through AD:

Back to Top

 

Start Your Synchronization

If you've completed everything above, your ADI service is now configured and may be started in one of two ways:

  1. By using the Windows Service Control Manager (the service is called "Active Directory Integration Sync Service"), or
  2. By opening a command prompt in admin mode, navigating to the below directory as applicable, and typing "ADIsync.exe service start".
    • C:\Program Files (x86)\KnowBe4\ADISync (default location on 64 bit platforms)

The sync service will attempt to run immediately after start and every six hours after that.

Remember to keep Test Mode enabled until you are sure you have set up ADI in a way that meets your organization's needs. Once you're happy with your ADI setup, you can disable Test Mode and update your KnowBe4 Account Settings. Your next ADI sync will provision your users as expected.

Back to Top

 

Advanced Configuration Options

Multiple Source Domain Support

If your users are split between multiple domain sources, you will need to set up a configuration for each domain to be queried. This is done by running “ADIsync.exe config” as an Administrator in the installation directory for each of the additional domains. This will create the additional <domain>.conf files, which you can then edit to contain the desired filter criteria as explained above.

To run ADI Sync again:

  • Open Command Prompt
  • Browse to the \ADIsync system directory
  • Enter ADIsync.exe config
  • Enter the details for your additional domain/DC

Check out our Service Configuration steps for more details.

This will create the additional <domain>.conf files which may be edited with filter criteria, with what OUs, users, and groups you'd like to include/exclude as you normally would.

NOTE: The system where ADI sync is installed must be able to connect to both DCs.

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, we allow you to alter where you'd like to pull email addresses from in Active Directory or choose to sync ONLY the primary proxy email address of the user.

You can open your ADISync.conf file from within C:\Program Files\KnowBe4\ADISync and you will see the following available fields by default:

  • emailAttribute = "proxyAddresses"
  • primaryproxyonly = false

Here is how to change what email addresses sync (the 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, save the .conf file, and start the ADI service again. This will make sure no alias email addresses are synced.
  • Mail Attribute: If you'd like to change to use the Mail attribute instead of proxyAddresses, change the emailAttribute to "mail" instead of "proxyAddresses", save the .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 our purposes, this value does not need to be a valid domain. If your organization does not want to use this attribute, please contact support and they will be happy to assist you.

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

If you don't see the emailAttribute field in your ADIsync.conf file, it is likely you are using an older version of ADI, and if you need to make one of the above changes, you should upgrade to the latest version of ADI.

Back to Top

  

How Do I Install the Newest Version of ADI?

You can install the newest version of ADI right over your previous version. To do this, follow the steps below:

  1. Download the new installer 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.

As of version 1.0.16.5, we added additional sync fields for more customization. To use the updated sync fields, you must install this version of ADI and then manually start the service. After starting the service, your existing <domain>.conf file(s) will be updated with the new sync fields. If you decide to customize the new fields, the service must be run again for your changes to sync.

Back to Top

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.

Related articles