×

Active Directory Integration (ADI) for KnowBe4

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 synchronisation, and no information will be sent back to your Active Directory from the KnowBe4 console.

Prerequisites

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.
    • 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).
  • Make sure you have this information ready:
    • NOTE: if you have multiple domains with user objects for synchronisation, you’ll want to have that information ready as well.
    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 simply the root domain for your Active Directory, i.e., organization.com.
    3. 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.
  • Access your Account Settings: First, log into 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:
    • IMPORTANT: 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 synchronisation 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 for you to resolve any potential issues without affecting current users in the console.
    1. Obtain your Active Directory Synchronisation 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’.
    2. 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.
    3. Download the Active Directory Sync Tool: This is the .msi file located in your Account Settings area.
  • Know what users you want to synchronise: 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 synchronisation 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 organised 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.

Once these configurations are done and the required information is on hand, you’re ready to set up your AD Integration.

Installation and Configuration

Service 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 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.
  2. 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)
  3. You’ll be prompted to enter all of the below information:
    • Note: LDAPS is not enabled on most Domain Controllers. 
    • The first time this command is run, you will be prompted for the Active Directory Synchronisation 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 synchronisation. You need to ensure you have edit permissions on the ADISync folder.

Important: If you do not need to use certain fields for inclusion/exclusion, simply leave them as-is.

Sync Users by Inclusion/Exclusion of OU, Group, or Specific User

In order for your ADI integration to work properly, you will need to include at least one OU, group, or user beneath the sync.users portion of the .conf file.

The following options are for identifying user objects to be synchronised and are located under the [sync.users] portion of the .conf file:

includedOUs = List of OUs that will be searched for users.

  • Specified OUs are recursed and all mail-enabled accounts that are not disabled will be found. For example, if “Users” is specified, then any qualifying user objects within that OU or underlying OUs (and underlying OUs under those OUs, and so on) will be included.
    Note: Using this field will not search for users within groups, within the specified OUs. Use the includedGroups field (below) to sync users from security or distribution groups.
  • If you want to specify an OU that is beneath a root level OU, you must use reverse syntax separated by a forward slash. For example, if there is a root OU called “All Users” and beneath that there is an OU called “Accounting”, you would format this as “Accounting/All Users”.
  • Additionally, if multiple OUs are to be specified they need to be enclosed in double quotes and separated by commas, all of which is encapsulated in brackets.
    • For example: includedOUs = [“Accounting/All Users”,”Development/All Users”]

excludedOUs = List of OUs that will be searched for users that will be excluded.

  • If there are excluded users found, they will cancel out any OU users that are specified for inclusion.
  • The syntax for the excludedOUs is the same as for includedOUs. 
    • For example: excludedOUs = [“Contractors/Development/All Users”]

includedGroups = List of groups that will add users that are either directly or indirectly members of the specified Active Directory security or distribution groups.

  • For example, if there is a group called “Accounting” which contains 4 user accounts and a group called “Finance”, then all 4 users accounts in “Accounting” will be included, as well as any members of the “Finance” group.
  • Users found in this manner will override users defined for exclusion by “excludedOUs”.
  • If you want to import ALL of the users in your AD, you can easily do this by simply including the Domain Users group in the includedGroups entry. By default, all of the users in AD will be members of Domain Users.
  • Multiple groups need to have each group enclosed in double quotes and separated by commas, all of which must be encapsulated in brackets.
    • For example: includedGroups = [“Accounting”,”Human Resources”]

excludedGroups = List of groups that will exclude users that are either directly or indirectly members of the specified Active Directory security or distribution groups.

  • If there are users found in this configuration, they will cancel out users that are found in either includedOUs or includedGroups. The syntax is the same as includedGroups.
    • For example: excludedGroups = [“Contract Employees”]

includedUsers = List of users to be explicitly included.

  • Users are specified using “username@domain.com” syntax and multiple users may be specified using syntax similar to prior options.
  • Any users specified in this option will override any prior exclusion by group or OU.
    • For example: includedUsers = [“mwhite@knowbe4.com”]

excludedUsers = List of users to be explicitly excluded.

  • This uses the same “username@domain” syntax as includedUsers and multiple users may be specified.
  • Any users specified in this option will be excluded regardless of any inclusion rules.
    • For example: excludedUsers = [“jsmith@knowbe4.com”,”mjones@knowbe4.com”]

Sync Groups by Inclusion/Exclusion of OU or Group

After criteria for user synchronisation has been defined (this is required), one may optionally set groups for synchronisation. These are AD groups which will show up in the KnowBe4 console as groups, which you can target as desired with Phishing or Training campaigns. If a user is directly or indirectly a member of a group in AD then they will directly be a member of that group in the KnowBe4 console (NOTE: KnowBe4 does not support nested groups).

It is important to note that ONLY users found in the earlier process will have their membership shown in these synchronised groups. If a group is specified for synchronisation but no synchronised users are members (directly or indirectly) then the group will not be synchronised.

*Important: only security and distribution groups will be added or synced as Groups in the console. When you include OUs in your sync, groups within that OU will be added or synced as Groups in the console, not the OU itself. 

The following options are for identifying groups to be synchronised and are located under the [sync.groups] portion of the .conf file:

includedOUs = A list of OUs that will be recursively searched for security or distribution groups.

  • Only groups specifically found under the specified OU structure will be included.
  • Syntax is similar to earlier OU syntax, in that multiple OUs may be specified, with each enclosed by double quotes, separated by commas, and entirely encapsulated in brackets.
    • For example: includedOUs = [“Accounting/All Users”,”Development/All Users”]

excludedOUs = A list of OUs that will be recursively searched for security or distribution groups that will not be synchronised.

  • Syntax is the same as other OU options.
    • For example: excludedOUs = [“Contractors/Development/All Users”]

includedGroups = A list of specific security or distribution groups to be synchronised.

  • Any groups specified will be synchronised and members (direct or indirect) that are included in the user sync will be populated.
  • This option overrides any excluded groups from the earlier “excludedOUs” option under sync.groups.
    • For example: includedGroups = [“Sales”,”Accounting”]

excludedGroups = A list of specific groups to be excluded from synchronisation.

  • Any groups specified will not be synchronises.
  • This option overrides any groups specified in includedOUs or includedGroups specified in sync.groups.
    • For example: excludedGroups = [“Consultants”]

Once the filter criteria has been set, save the file. You may need to give yourself appropriate write permissions to do so.

Syncing Other User Information to KnowBe4 from AD

Also in the”<your domain here>.conf” file are the following fields, which by default will automatically populate the user information fields in your KnowBe4 console as defined in AD.

If you’d prefer NOT to import certain fields, simply delete the content contained in the quotation marks to the right of the equal sign (do NOT delete the quotation marks or the whole line of text, only what is between the quotation marks).  If you delete the whole line, the service will automatically add it back in and sync what you don’t want to sync. 

[sync.fields]
first-name = "givenName"
last-name = "sn"
phone-number = "telephoneNumber"
mobile-number = ""
location = "physicalDeliveryOfficeName"
division = "division"
manager = "manager"
title = "title"
employee-number = "employeeNumber"

Additional lines cannot be added. We’ve included all available lines above.

Start Your Synchronisation

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\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 6 hours after that.

The details of the synchronisation 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.

Advanced Configuration Options

Multiple Source Domain Support

If your users are split between multiple domain sources, you will need to setup 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

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. Simply download the new installer from your KnowBe4 Account Settings, run the installation, and close the DOS prompt that appears at the close of installation.

As of version 1.0.7.3 we’ve added a new field to the ADIsync.conf file called emailattrib. You will only need to update if you want to use something other than Proxy Addresses, Primary Proxy Addresses, or the Mail Attribute for syncing your users’ email addresses.

For more information and general guidance on our products & services, please contact us.

Require further support?

Search all Knowledgebase articles

Send a Support Request to The Idency Support Team

Active DirectoryADIintegrationknowbe4security awarenesstraining platform

In good company: some of Idency's clients