Below are some commonly-asked questions about KnowBe4's ADI feature. If you don't see the answer you need, submit a ticket to our support team.
Jump to:
- What would be the advantage of AD integration with the KnowBe4 console?
- What is our encryption method for the data that gets transferred between the ADI tool and KnowBe4 servers, and how is my user data protected on your servers?
- What is the purpose of Test Mode and when should I turn it off?
- Can I modify how often my AD information will sync to KnowBe4?
- How do I sync my AD groups with my KnowBe4 groups?
- What should I do if my AD is not structured in an ideal way for syncing with ADI?
- How do I limit what data Active Directory syncs to KnowBe4? or How do I change which Active Directory fields the ADI Sync tool pulls data from?
- How do I set a user to not be AD-managed?
- If I make changes to the KnowBe4 console, will any changes happen in my Active Directory?
- Can I use ADI if I'm using Azure?
- How can I enable LDAPS before syncing my Active Directory to KnowBe4?
- If I add a user to a Group in the KMSAT console, and the user is NOT in that Group in Active Directory, will the user be removed from the Group in the console the next time we sync?
- How do I enable detailed logging to discover what errors may be happening with my import?
- How do I manage my ADI if I have multiple source domains? or I have multiple domains and multiple domain controllers that do not talk to each other. Is it possible to sync everything to my one KnowBe4 account?
- My users have multiple email addresses in Active Directory. Which one will be the primary in my KnowBe4 console?
- What does enabling the "Show Group Domain" option in my Account Settings do?
- The ADI tool is not finding any email addresses for my users.
- I am having difficulties with including/excluding specific users and groups.
- The ADI sync file has a “post-URL” where the information is being sent to. Is that secure and what happens to the information?
- How can I add comments to my <domain>.conf file?
- My OUs did not get added as Groups in the KnowBe4 console during my sync.
- I am an MSP and I have a multi-tenant Active Directory domain. How can I set up ADI for my clients?
- Why can't I sync contact objects with ADI?
- I don't have Edit Permissions to save my <domain>.conf file so I can't configure my LDAP filter.
- My organization has proxy or firewall in place. How can I connect ADI successfully?
- I have lots of disabled users in my Active Directory environment. Will these users sync too?
- I need to change the initial credentials/login that were used to set up ADI for my organization. How can I do this?
- Will my users' passwords sync to the KnowBe4 console?
- I'm getting a "No Valid Email Address" error next to several users. What does this mean?
- I'm on the EU instance of KnowBe4 and my sync failed. What do I do?
- How can I exclude AD accounts from my sync that haven't logged on in the past XX number of days?
- How can I exclude expired AD accounts from my ADI sync?
- How often can I request an ADI API sync?
- Is there a file that I can download that shows the sync errors and details?
- I got a "Not Enough Space" error after an ADI Sync attempt. How can I fix this?
- Will my existing phishing and training campaigns be impacted when I turn on ADI?
- I got a "Cowardly refusing to synchronize" error after an ADI Sync attempt. How can I fix this?
1) Question: What would be the advantage of AD integration with the KnowBe4 console?
Answer: ADI will allow you to manage your user list in KnowBe4 through Active Directory. Changes to your AD will be reflected in your KnowBe4 console at each sync, meaning if users are archived in AD, they will be archived in KnowBe4. Additionally, user information can be automatically pulled into the KnowBe4 console which will allow you the benefit of using placeholders for user information in your phishing campaigns.
2) Question: What is your encryption method for the data that gets transferred between the ADI tool and KnowBe4 servers, and how is my user data protected on your servers
Answer: We use HTTPS/SSL for the data that gets transferred between the ADI tool and our servers. We use LDAP/LDAPS to communicate between your domain controller and our ADI tool. By default, your tool will utilize LDAP unless you enable SSL at the time you are setting up the ADI tool. To enable SSL, you MUST already have LDAPS enabled. More details on that can be found here.
The username and password data supplied for use with the directory is stored and encrypted using XSalsa20 and Poly1305 mechanisms, the latter being a derivative technology of AES. This is how we protect the account data stored in the <domain>.dat file on disk.
Once the data is on our side, it is granted the same data protection as other items as described in our privacy policy, which you can review here.
3) Question: My account is on Test Mode. What is the purpose of test mode and when should I turn it off?
Answer: Each account will begin Active Directory Integration (ADI) on test mode. It is very important that you leave your account on test mode to begin with so that you can review what will happen when you actually integrate your KB4 console with Active Directory. Test mode will show you all of the changes that are going to take place, and gives you an opportunity to make changes or correct items as needed. Once you are fully satisfied with the proposed changes you see on test mode, then you can move forward with unchecking the test mode option on your account.
4) Question: Can I modify how often my AD information will sync to KnowBe4?
Answer: By default, the service will run every six hours. If you need to force the sync immediately, you can restart the service. If you'd like to modify the sync interval you can do so by changing the sync-interval field in your ADIsync.conf file.
The minimum sync interval is 6 hours (6h0m0s).
5) Question: How do I sync my AD groups with my KnowBe4 groups?
Answer: The groups are based on security groups and distribution groups in AD. If you have a group in AD called “Southeast”, for example, and you want to sync the users of that group, you need to include that group in the [sync.groups] portion of the <domain>.conf.
There are two ways to include a group for membership synchronization: 1) either includeOUs if you have all the groups you want to sync in one place, or 2) includeGroups if you want to explicitly call out groups to synchronize. It’s important to note that the [sync.groups] section is only for finding group membership of the users that are found in the [sync.users] portion of the config. For example, let’s say that your “Southwest” group in AD has 100 members, either directly or because there are other groups of users inside it. If only 85 of those people are picked up because of the settings in [sync.users] then you’ll only have those 85 users in the “Southwest” group in the console once you add “Southwest” under the [sync.groups] config.
6) Question: The groups/users in my AD are not structured the way I want them to be on the KnowBe4 console. What should I do?
7) Question: How do I limit what data Active Directory syncs to KnowBe4? (Or: How do I change which Active Directory fields the ADI Sync tool pulls data from?)
Answer: You can reduce the amount of synchronized information that syncs to KnowBe4. Inside the <your domain here>.conf file you will see an area with settings like this:
[sync.fields]
comment = ""
custom-date-1 = ""
custom-date-2 = ""
custom-field-1 = ""
custom-field-2 = ""
custom-field-3 = ""
custom-field-4 = ""
department = "department"
division = ""
employee-number = "employeeNumber"
employee-start-date = "whenCreated"
first-name = "givenName"
last-name = ""
location = "physicalDeliveryOfficeName"
manager = "manager"
mobile-number = ""
organization = "o"
phone-number = "telephoneNumber"
title = "employeeNumber"
You can remove the data on the right of the equal sign and just leave the double-quotes. This will not send data or overwrite existing data for those fields.
You can also change the data in the quotes to reflect the proper field in Active Directory where your user information exists. Keep in mind, this field is case sensitive and must match the Attribute name in AD.
The mobile field is purposely left blank as there is no mobile field in Active Directory. Here you can decide which field you'd like to pull by filling in between the quotations. Also, the input for the custom date fields must follow the mm/dd/yyyy format.
8) Question: How do I set a user to not be AD-managed?
Answer: There are two ways of doing this. You can set it up for each user individually, or you can gather a list of user email addresses who should not be managed by AD and place them in a CSV which contains only two fields: "Email" and "Provisioning Managed".
An example of this set-up is below:
| Provisioning Managed | |
| user1@domain.com | false |
| user2@domain.com | false |
| user3@domain.com | false |
| user4@domain.com | false |
Once you import that CSV through the normal means of Importing users via a CSV file, you can set those users to not be provisioning-managed.
9) Question: If I make changes to the KnowBe4 console, will any changes happen in my Active Directory?
Answer: No. KnowBe4's ADI feature is a one-way process of synchronization, and only changes made in Active Directory will affect the KnowBe4 console.
10) Question: Can I use ADI if I'm using Azure?
Answer: Yes, you can. To use ADI with Azure, follow these instructions: Using ADI With Azure Active Directory Domain Services
You can also set up Azure for single sign-on with KnowBe4. For more information on this, check out our article: Configuring Single Sign-on with Azure AD
11) Question: I want to enable LDAPS before syncing my Active Directory to KnowBe4. What is the best way to go about this?
Answer: This TechNet article will be able to walk you through steps to enable LDAPS: LDAP over SSL (LDAPS)
You can test out that LDAPS was implemented successfully. Once you are set up with LDAPS, you can proceed with your ADI setup. Ensure you set the use-ssl field to ''true" if you're using LDAPS.
12) Question: If I add a user to a Group in the KMSAT console, and the user is NOT in that Group in Active Directory, will the user be removed from the Group in the console the next time we sync?
Answer: Yes, if the Group in question is an AD-synced Group. For example, if you have a “Clickers” Group in the console only, you can do whatever you like with membership of the Group and include both AD-enabled accounts and non-AD enabled accounts. However, if you then sync an AD Group called “Clickers”, it will be driven by AD for AD enabled accounts.
Non-AD managed users can also be put into AD-managed Groups, however, and the AD sync won’t do anything with those users' Group membership.
13) Question: How do I enable detailed logging to discover what errors may be happening with my import?
Answer: Navigate to your ADISync directory and open your ADISync.conf file. Set the logging level from log-level = "ERROR" to log-level = "TRACE" in this file. The next time the sync occurs, you'll see more detailed information on what may have happened to cause errors with your sync. To view your error logs, navigate to the directory KnowBe4\ADISync\logs.
14) Question: How do I manage my ADI if I have multiple source domains but want to sync everything to a single KnowBe4 account? (Or: I have multiple domains and multiple domain controllers that do not talk to each other. Is it possible to sync everything to my one KnowBe4 account?)
Answer: 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.
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.
15) Question: If I have multiple domains in AD and I am importing users into the console with ADI, how does it determine which address to use as the primary?
Answer: When a user has multiple email addresses in exchange there can only be one “Primary” which is the reply-to address. We attempt to use that one as the primary for the user.
16) Question: What does enabling the Show Group Domain option in my Account Settings do?
Answer: If your users are split between multiple domain sources, enabling this option will allow you add the root domain to each of the AD-synced group names in the KnowBe4 console so that you can better organize your users. For example, an "Accounting" group synchronized from the domain of KnowBe4.com would be called KnowBe4.com\Accounting once the sync took place.
17) Question: The ADI tool is not finding any email addresses for my users.
Answer: Are you using a mail server other than Exchange or Microsoft 365? If so, this means your proxy address field in AD is most likely blank. The proxy address is what we will typically pull the email addresses from in AD to add to the KnowBe4 console.
To work around this, we’ll need to get the email address from another field in AD (typically, you'll want to use the mail attribute in these situations). Click here to view steps for how to change where we pull email addresses from in Active Directory: How Do I Change Where to Pull the Email Addresses from Active Directory?
18) Question: I am having difficulties with including/excluding specific users and groups.
Answer: Occasionally, issues with including/excluding certain users/groups in the sync can be caused because the person who is attempting to sync is not a Domain Admin.
You can use a Domain Admin to authenticate the ADI Sync tool to your Active Directory, or set up a new user in AD with the following permissions:
- Read all user information
- Read all inetOrgPerson information
See our article for instructions on How To Create An ADI Service Account In Active Directory
Using an account that is a member of Domain Admins will ensure adequate permissions but is not typically required. The account used to setup the AD Integration tool must have high enough permissions to query all data. (if not, this could result in some information not syncing)
So, if you do have minor issues with your sync, try to switch the service to use your full Domain Admin (DA) account or the account that you're using ADUC (AD Users and Computers) with. To do so, delete the <domain>.dat file and re-run “adisync.exe config” (as an administrator).
- To change the specified user:
- Browse to the \ADIsync folder and delete the file named: <domain>.dat
- Then, open an elevated CMD and browse to the \ADIsync folder, and then type: ADIsync.exe config
19) Question: The ADI sync file has a “post-URL” where the information is being sent to. Is that secure and what happens to the information?
Answer: It’s going directly to the same server(s) that process the other method of importing users (CSV uploads) and thus, it's using the same security processes associated with that. The users.json is what is getting sent over for processing. No other information is sent--we explicitly leave configuration data local to your system.
20) Question: How can I add comments to my <domain>.conf file?
Answer: You can do this by using a hash mark (#). You can comment anywhere except for in the middle of a line or at the beginning of a line
For example:
[sync.users]
includedOUs = ["Users", "Managers", "East Coast/Managers"] #I am commenting on my .conf file.
excludedOUs = [""]
includedGroups = ["Tech","KnowBe4 Group"]
excludedGroups = [""]
includedUsers = [""]
excludedUsers = [""]
21) Question: My OUs did not get added as Groups in the KnowBe4 console during my sync.
Answer: Only security and distribution groups will be added or synced as Groups in the console. When you include OUs in your sync (beneath the Sync Groups area of your domain.conf file), only groups within that OU will be added or synced as Groups in the console, not the OU itself.
22) Question: I am an MSP and I have a multi-tenant Active Directory domain. How can I set up ADI for my clients?
Answer: Because you will need to have an ADI installation for each KnowBe4 account, you will have to install the tool on a separate machine for each domain that you want to sync with. It's not possible at this time to have a single installation across multiple KnowBe4 accounts.
23) Question: Why can't I sync contact objects with ADI?
Answer: ADI can sync users or groups that are members of your Active Directory domain. Contact Objects represent users who do not log into your domain (and are not part of your domain). A contact object is just an object that can be looked up in the domain or Exchange. There are no permissions that can be assigned and the email address is an external address.
Because Contact Objects are not actually part of your domain, they cannot be synced with ADI.
See: Distinguishing between contacts and users
24) Question: I don't have Edit Permissions to save my <domain>.conf file so I can't configure my LDAP filter.
Answer: If you're receiving an error that you "cannot save due to edit permissions" and are unable to/unsure of how to grant permissions, contact your IT team or administrator to allow you to edit the folder containing your ADIsync files (Program Files/KnowBe4/ADI Sync).
If you have the ability to edit the Permissions of the ADISync folder, do the following steps:
STEP 1) Navigate to your ADIsync folder. It may be located under Program Files (x86)/KnowBe4 OR Program Files/KnowBe4.
STEP 2) Right-click your ADIsync folder, and click Properties.
STEP 3) Click Security, then click Edit.
STEP 4) Click Add to add your user account.
STEP 5) Type in your username, and click Check Names.
STEP 6) If your account is showing correctly after clicking Check Names, click OK.
STEP 7) Beneath your username, toggle on the Allow checkbox next to Full control, giving you full permissions over the ADIsync folder. Click OK, then click OK on the ADIsync Properties box. You will now have the required permission to edit the <domain>.conf file.
25) Question: My organization has a proxy or firewall in place. How can I connect ADI successfully?
Answer: You can integrate with Active Directory even if you're using a firewall or proxy. See this article for more details: How Do I Connect to Active Directory Integration ADI Through a Proxy?
26) Question: I have lots of disabled users in my Active Directory environment. Will these users sync too?
Answer: No, users with disabled accounts in Active Directory will not sync. However, you can modify the LDAP filters within the ADIsync.conf to sync disabled managers.
27) Question: I need to change the initial credentials/login that were used to set up ADI for my organization. How can I do this?
Answer: First, browse to the \ADIsync folder and delete the .dat file you see there. Next, open an elevated command prompt window and browse to the \ADIsync folder, and then type: ADIsync.exe config
You will need to enter your new credentials during the configuration.
28) Question: Will my users' passwords sync to the KnowBe4 console?
Answer: No. The ADI sync does not query your AD passwords. No passwords are synced back to your KnowBe4 account.
29) Question: I'm getting a "No Valid Email Addresses" error next to several users. What does this mean?
Answer: Are you receiving this exact error? (Shown below)
This error typically occurs if you do not have all of the domains in your Active Directory "allowed" on your KnowBe4 account (for example, ABC.com and ABC.co.uk).
To fix this, you can add your additional domains to your account. For more information on how to do this, visit our How to Add and Verify Allowed Domains article. Once the additional domains are added, this error will be corrected upon the next sync.
30) Question: I'm on the EU instance of KnowBe4 and my sync failed. What do I do?
Answer: If this happens, please edit the ADIsync.conf file and update the post-URL.
Currently, it is:post-url = "https://training.knowbe4.com/api/v1/ldap/user_upload"
It needs to be:post-url = "https://eu.knowbe4.com/api/v1/ldap/user_upload"
Once that is done, please save the file and restart the service. If this does not solve your issue, or if the post-url is already correct and your sync is still failing, please contact Support.
31) Question: How can I exclude AD accounts from my sync that haven't logged on in the past XX number of days?
Answer: You can exclude AD user accounts from syncing to KnowBe4 based on the lastLogonTimeStamp AD account attribute. You'll do so by adding a lastLogonTimeStamp parameter to the following two LDAP filters in your domain.conf file:
- filter_users_by_ou
- filter_users_by_group
The lastLogonTimeStamp must be in Integer8 syntax. Integer8 values represent the number of 100-nanosecond intervals since 12:00 am January 1, 1601.
Integer8 syntax example:
| Standard Format | Integer 8 Syntax |
| 5/21/2017 10:41:52 am Eastern Time | 131398513120000000 |
Here are two sources you can use to convert date/time to Integer8 syntax:
https://www.epochconverter.com/ldap
https://www.silisoftware.com/tools/date.php
Follow the steps below to exclude users from your sync based on the last login date of your choice:
- Decide on the last login date/timestamp to use as the cutoff parameter for not syncing users to the console. (For example, MM/DD/YYYY, three months prior to today)
- Convert this date to Integer8 syntax.
- Add this parameter to the following two fields in the domain.conf file, as shown in red below (where XXXXXXXXXXXXXXXXXX is the timestamp, in Integer8 syntax).
filter_users_by_ou =
"(&(lastLogonTimeStamp>=XXXXXXXXXXXXXXXXXX)(objectCategory=person)(objectClass=user)(mail=*)(!userAccountControl:1.2.840.113556.1.4.803:=2)(!cn=HealthMailbox*)(!cn=SystemMailbox*))"
filter_users_by_group =
"(&(lastLogonTimeStamp>=XXXXXXXXXXXXXXXXXX)(objectCategory=person)(objectClass=user)(mail=*)(!userAccountControl:1.2.840.113556.1.4.803:=2)(!cn=HealthMailbox*)(!cn=SystemMailbox*)(|{DYNAMIC_CONTENT}))"
Keep the remaining filters in this portion of the domain.conf file, as is.
NOTE: Keeping this exclusion current will require a manual update every so often. For example, if you want to omit accounts that haven't logged in for 90 days, every 90 days you'll have to edit the domain.conf file to change the timestamp (lastLogonTimeStamp>=XXXXXXXXXXXXXXXXXX) to 90 days prior to the present day.
32) Question: How can I exclude expired AD accounts from my ADI sync?
Answer: You can exclude expired AD accounts from syncing to KnowBe4 by adding a parameter to the following two LDAP filters in your domain.conf file:
- filter_users_by_ou
- filter_users_by_group
Follow the steps below to exclude AD accounts from your sync based on the expiration date of the account(s):
- Decide on the date/timestamp to use as the cutoff parameter for not syncing users to the console. (i.e., accounts expired on or before MM/DD/YYYY will not be synced)
- Convert this date/timestamp to Integer8 syntax. See the previous question for more information on Integer8 syntax.
- Add this parameter to the following two fields in the domain.conf file, as shown in red below (where XXXXXXXXXXXXXXXXXX is the timestamp, in Integer8 syntax).
filter_users_by_ou =
"(&(l(accountExpires>=XXXXXXXXXXXXXXXXXX)(accountExpires=0))(objectCategory=person)(objectClass=user)(mail=*)(!userAccountControl:1.2.840.113556.1.4.803:=2)(!cn=HealthMailbox*)(!cn=SystemMailbox*))"
filter_users_by_group =
"(&(l(accountExpires>=XXXXXXXXXXXXXXXXXX)(accountExpires=0))(objectCategory=person)(objectClass=user)(mail=*)(!userAccountControl:1.2.840.113556.1.4.803:=2)(!cn=HealthMailbox*)(!cn=SystemMailbox*)(|{DYNAMIC_CONTENT}))"
Keep the remaining filters in this portion of the domain.conf file, as is.
NOTE: Keeping this exclusion current will require manual updates. The admin will have to update the timestamp (accountExpires>=XXXXXXXXXXXXXXXXXX) in the domain.conf file to exclude accounts that expired after this initial exclusion has been made.
33) Question: How often can I send an ADI API sync request?
Answer: KnowBe4 limits your ADI API sync frequency to once every six hours. When first setting up your ADI and using test mode, it's acceptable to start/stop the ADI service more often. Once test mode is off, however, you must limit your sync to once every six hours.
34) Question: Is there a file that I can download that shows the sync errors and details?
Answer: Yes! You can also download a text file that includes information about all of the sync changes and detailed error information. This file can be found in the top right corner on the Details Page of the sync that you selected.
35) Question: I got a "Not Enough Space" error after an ADI Sync attempt. How can I fix this?
Answer: First, make sure that you meet the minimum specifications listed here. If you do and you are still having issues, you may be able to resolve this error by installing the latest version of Windows Server 2019. However, if the update does not resolve this issue, please contact our support team and they will be happy to assist you.
36) Question: Will my existing phishing and training campaigns be impacted when I turn on ADI?
Answer: Users who are added to the console will also be enrolled in any phishing or training campaign that has the "Enable automatic enrollment for new users" option selected. Before adding users, we recommend checking the settings for each of your campaigns and disabling this option as needed.
37) Question: I got a "Cowardly refusing to synchronize" error after an ADI Sync attempt. How can I fix this?
Answer: This error can be caused by not specifying where your users should be pulled from in the domain.conf file. Open your domain.conf file and make sure the location is defined. If you are in a multi-domain environment, make sure to check every domain.conf file. If you are still seeing this error, please contact our support team and they will be happy to assist you.
Comments
0 comments
Article is closed for comments.