This manual will cover how to set up Active Directory Integration (ADI) with your KnowBe4 console.
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.
We also have a video which shows how to set up Active Directory Integration--first, though, we recommend that you read through the below documentation.
- Multiple Source Domain Support
- How Do I Change Where to Pull the Email Addresses from Active Directory?
- How Do I Install the Newest Version of ADI?
What are the benefits of setting up ADI?
It 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 be carried over to your KnowBe4 console automatically at the time of the next sync.
You can set up campaigns that will work with your integration to automate security awareness training for new employees. Imagine that when a new employee comes on board in your organization, as soon as you add them to your Active Directory and the ADI sync occurs, they will 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.
How ADI Operates
New Customers vs. Existing Customers
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'd like to set up phishing and training campaigns for.
For existing customers, it is important that the setup and configuration of your ADI are completed in such a way that current user account information is maintained and nothing unexpected occurs. 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. Also by default, 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 are considered to be 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 out to the console.
For existing customers with console-managed user accounts, an automatic process will match console-managed user accounts with AD user accounts in order to turn the console-managed accounts into AD-managed user accounts. This process works as follows:
- Customer installs and configures the ADI Sync component at their site.
- This 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.
Before you begin setting up ADI, you should complete the below steps and gather the required information to streamline your setup process.
- Confirm your set-up meets our basic requirements:
- Active Directory: Microsoft Active Directory running at functional level 2003 or higher
- Azure Active Directory: Azure Active Directory Domain Services. See: Setting up ADI with Azure AD Domain Services
- Service: Windows Desktop 7/Vista/8/10 or Windows Server 2003/2008/2012/2016 (32 or 64 bit). Also, ensure your PC (where ADI is installed) can reach https://training.knowbe4.com (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).
- If you're using a mail server other than Exchange or Office 365, click here for specific instructions to assist you with your sync.
- If you're configuring ADI through a proxy, you'll need to also follow the instructions on this article.
- Make sure you have this 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
- IP address or FQDN for an AD Directory Controller: By default, all Domain Controllers are set up to respond to LDAP requests.
- AD Domain Name: This is simply the root domain for your Active Directory, i.e., organization.com.
- Username/Password to query LDAP: An AD account which has access rights to perform LDAP queries; by default, any account in "Domain Users" group has sufficient permissions. If the AD account you're using is not a domain admin, you will want to ensure that account has certain "read" permissions to your AD. See: How to create an ADI Service Account in Active Directory
- Access your Account Settings:
First, log in to your KnowBe4 console. Click your email address on the top right and then click on "Account" to view your account options. Once there, complete the following three steps:
In your Account Settings, you will see that the "Test Mode" option is checked by default. This MUST remain checked until you have completed setting up the synchronization and verified that it is operating correctly. While 'Test Mode' is enabled, nothing is actually altered with the users in the KnowBe4 console. Rather, a report is generated showing what would have happened if the sync took place. This allows you to resolve any potential issues without affecting current users in the console.
- Obtain your Active Directory Synchronization Token: Your account's AD Sync token is located in your KnowBe4 console under your Account Settings. The 32 digit key is located under the Active Directory Integration set of options and will look similar to '9X140X4829E37XX545401X97912X604X'.
- Enable ADI on your Account: Check the "Active Directory Integration Enabled" option located in the same Account Settings area and click the "Update Account Info" button to save the settings.
- Download the Active Directory Sync Tool: This is the .msi file located in your Account Settings area.
- 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 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 and are not sure, 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.
- 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?
Once these configurations are done and the required information is on hand, you're ready to set up your AD Integration.
Installation and Configuration
Once you've gathered all the information you need, you're ready to begin installing and configuring your ADI Sync.
- Run the Active Directory Sync Tool (the .msi file from beneath your console's Account Settings). The service 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.
- A command prompt will be opened and will navigate to the installation directory automatically:
- C:\Program Files\KnowBe4\ADISync (default location on 32 bit platforms)
- C:\Program Files (x86)\KnowBe4\ADISync (default location on 64 bit platforms)
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.
- 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 is completed.
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.
LDAP Filter Configuration
After the above steps have been completed successfully, there will be a <your domain here>.conf file located in the installation directory. Open this file in a text editor (such as Notepad) and specify the filter criteria for user and group synchronization. You need to ensure you have edit permissions on the ADISync folder.
This configuration is required in order to sync users from AD, so you must include at least one OU, group, or user beneath the sync.users portion of the .conf file. Visit the sections below to learn more about syncing information to KnowBe4 through AD:
- Sync Users by Inclusion/Exclusion of OU, Group, or Specific User
- Sync Groups by Inclusion/Exclusion of OU or Group
- Syncing Other User Information to KnowBe4
Start Your Synchronization
If you've completed everything above, your ADI service is now configured and may be started in one of two ways:
- By using the Windows Service Control Manager (the service is called "Active Directory Integration Sync Service"), or
- By opening a command prompt in admin mode, navigating to the below directory as applicable, and typing "ADIsync.exe service start".
- C:\Program Files\KnowBe4\ADISync (default location on 32 bit platforms)
- 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.
The details of the synchronization results are located in the KnowBe4 console under the Users > Active Directory tab. Here you can see what users are being added, what users are set to be managed by Active Directory, and what users will be archived.
The 'Test mode' icon indicates that the import was run while in Test mode. Test mode doesn’t actually make any changes to console users and groups--the report is meant to indicate what would have happened. This gives you an opportunity to review the import results and make changes and corrections as needed. Once you are happy with what you see in your Users > Active Directory report, feel free to uncheck Test mode in your Account Settings and run your actual import.
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.
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 - note that 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.
- 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.
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:
- Download the new installer from your KnowBe4 Account Settings.
- Run the installation.
- Close the DOS prompt that appears at the close of installation.
- Start the sync service.
As of version 18.104.22.168, 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.