ADI FAQ
In this article, you can find frequently asked questions about using Active Directory Integration (ADI) to integrate your Active Directory (AD) with your KMSAT account. If you have additional questions that this article does not include, please submit a ticket to our support team.
To learn more about using ADI to integrate your AD account with KMSAT, see our Active Directory Integration (ADI) Configuration Guide.
Jump to:
General Information
For general information about ADI, see the questions below:
1. What is the advantage of integrating Active Directory with my KMSAT account?
2. Can I use ADI if I'm using Microsoft Azure?
3. How do I change the initial login credentials that were used to set up ADI for my organization?
4. Will my existing phishing and training campaigns be impacted when I turn on ADI?
5. If I make changes to my KMSAT account, will any changes happen in my Active Directory?
7. What is KnowBe4's encryption method for data that is transferred between the ADI tool and KnowBe4 servers, and how does this encryption method protect my user data?
1. What is the advantage of integrating Active Directory with my KMSAT account?
You can use ADI to manage your user list in KMSAT through Active Directory. The changes that you make to your AD account will affect your KMSAT account at each sync. For example, if you archive a user in your AD account, the ADI sync will archive that user in your KMSAT account.
Additionally, you can specify which user information is automatically synced into your KMSAT account. Then, you can use some of this information in user placeholders when you create phishing campaigns. For more information about user placeholders, see the User Information Placeholders section of our How to Use Placeholders article.
2. Can I use ADI if I'm using Microsoft Azure?
Yes. To use ADI with Azure, follow the instructions in our How to Use ADI with Microsoft Entra ID article.
You can also set up Azure for single sign-on (SSO) with KMSAT. For more information, see our How Do I Configure SSO/SAML with Microsoft Entra ID? article.
3. How do I change the initial login credentials that were used to set up ADI for my organization?
To change your ADI login credentials, follow the instructions below:
- From your computer, navigate to the ADIsync folder.
- Delete the .dat file from the folder.
- Open an elevated command prompt window.
- Navigate to the ADIsync folder in the command prompt.
- Enter ADIsync.exe config into the command prompt.
- Enter your new credentials during the configuration.
4. Will my existing phishing and training campaigns be impacted when I turn on ADI?
When you turn on ADI, your phishing campaigns will not be impacted. Training campaigns may be impacted, depending on the campaign settings. If the training campaign has the Enable automatic enrollment for new users option selected, then users who are added to your KMSAT account will be enrolled in that training campaign. To learn how to enable this option, read our Creating and Managing Training Campaigns article.
5. If I make changes to my KMSAT account, will any changes happen in my Active Directory?
No. While the changes you make in Active Directory will affect your KMSAT account, the changes you make in your KMSAT account will not affect Active Directory.
6. If I have multiple domains in my AD account and I'm importing users into my KMSAT account with ADI, how does ADI determine which email address to use for my users' primary email address?
If your users have multiple email addresses in Active Directory, ADI will use the reply-to email address as your users' primary email address.
7. What is KnowBe4's encryption method for data that is transferred between the ADI tool and KnowBe4 servers, and how does this encryption method protect my user data?
We use HTTPS/SSL to encrypt the data that is transferred between ADI and KnowBe4 servers. Unless you enable SSL when you set up ADI, ADI uses LDAP/LDAPS to communicate between your domain controller and ADI. To enable SSL, you must already have LDAPS enabled.
To learn how to enable LDAPS, see question 2 in the Getting Started section below.
Getting Started
For information to help you get started with ADI, see the questions below:
1. Can I disable user provisioning for specific users?
2. How do I enable LDAPS before syncing my Active Directory to KnowBe4?
3. How can I add comments to my <domain>.conf file?
7. My organization has a proxy or firewall in place. How can I connect to ADI successfully?
9. What happens if I enable the Show Group Domain setting in my KMSAT Account Settings?
10. My KMSAT account is on test mode. What is test mode, and when should I turn it off?
1. Can I disable user provisioning for specific users?
Yes. To disable user provisioning for an individual user, follow the instructions in the Disabling User Provisioning for a Single User section of our How to Disable User Provisioning for a User article. To disable user provisioning for a group of users, follow the instructions in the Disabling User Provisioning for a Group of Users section of our How to Disable User Provisioning for a User article.
2. How do I enable LDAPS before syncing my Active Directory to KnowBe4?
To learn how to enable LDAPS, see TechNet's LDAP over SSL (LDAPS) Certificate article. The article also includes instructions for testing the LDAPS connection so that you can verify if it was enabled successfully.
3. How can I add comments to my <domain>.conf file?
You can add comments to your <domain>.conf file by entering the hash special character (#). However, you cannot add a comment at the beginning of a line or in the middle of a line.
For an example of a comment in a <domain>.conf file, see the section below:
[sync.users]
includedOUs = ["Users", "Managers", "East Coast/Managers"] #I am commenting on my .conf file.
excludedOUs = [""]
includedGroups = ["Tech","KnowBe4 Group"]
excludedGroups = [""]
includedUsers = [""]
excludedUsers = [""]
4. How do I manage my ADI if I have multiple source domains but I want to sync everything to a single KMSAT account? Or, how do I sync everything to one KMSAT account if I have multiple domains and multiple domain controllers that do not communicate with each other?
If your users are split between multiple source domains, you will need to set up a configuration for each domain that you want to sync to your KMSAT account. To learn how to set up a configuration for each domain, see the Support for Multiple Domain Sources section of our Active Directory Integration (ADI) Advanced Configuration Guide.
5. I am a Managed Service Provider (MSP), and I have a multi-tenant Active Directory domain. How can I set up ADI for my clients?
You will need to install ADI for each KMSAT account. For a successful installation, you'll need to install ADI on a separate machine for each domain that you want to sync with. At this time, you cannot use a single installation for multiple KMSAT accounts.
6. My AD users and groups are not organized how I'd like them to be organized in my KMSAT account. What should I do?
In Active Directory, you can create a new organizational unit, or OU, and add groups that are named after your KMSAT groups to the OU. For example, if you have a KMSAT group that is named "Group 1", you could create an AD group that is named “KB4-Group 1”. Then, you could add the AD users or groups that belong to that KMSAT group to the "KB4-Group 1" group. When you finish setting up this group, you can use this OU for the [sync.groups] or [sync.users] section of your <domain>.conf file. This method may be preferable because you will not need to change the existing groups in your AD account.
7. My organization has a proxy or firewall in place. How can I connect to ADI successfully?
You can integrate with Active Directory even if you're using a firewall or proxy. For more information, see our Can I Use Active Directory Integration (ADI) While Using a Proxy? article.
8. The ADIsync.conf file includes a post-URL where the information is being sent to. Is this post-URL secure, and what happens to the information?
The users.json file is being sent directly to the same servers that process imports when you import users with a CSV file. No other information is being sent for to the servers for processing. We intentionally leave the configuration data local to your system.
9. What happens if I enable the Show Group Domain setting in my KMSAT Account Settings?
When you enable the Show Group Domain setting, ADI will add your domain name to your AD-synced KMSAT groups. For example, a KMSAT group named "Accounting" that is synced with the domain "knowbe4.com" would be named "knowbe4.com\Accounting". If your users are split between multiple domain sources, this setting can help you organize your users.
10. My KMSAT account is on test mode. What is test mode, and when should I turn it off?
After you set up ADI, your KMSAT account will be on test mode until you turn it off. It's important that you leave your account on test mode so that you can preview what will happen when you sync your KMSAT account with Active Directory. To view this preview, log in to your KMSAT account, and navigate to Users > Provisioning. From the Provisioning tab, you can view the changes that will be made after you enable ADI. Then, you can resolve any potential issues without affecting the users that you have in your KMSAT account.
We recommend that you wait until you are fully satisfied with the preview before you turn off test mode. You can find the Test Mode setting in the User Provisioning section of your Account Settings.
Syncing Information
For syncing information about ADI, see the questions below:
1. Can I change how often my AD information syncs to my KMSAT account?
3. How do I sync my AD groups with my KMSAT groups?
4. How often can I send a sync request for ADI API?
5. How can I exclude expired AD accounts from my ADI sync?
6. How can I exclude AD accounts that haven't logged on in the past XX number of days in my sync?
9. Why can't I sync contact objects with ADI?
10. Will my users' passwords sync to my KMSAT account?
11. I'm using Carbon Black Cloud and am having issues with my KnowBe4 ADI. What should I do?
1. Can I change how often my AD information syncs to my KMSAT account?
Yes. By default, the ADI sync service will sync your AD account to your KMSAT account every six hours. If you need to force the sync to happen immediately, you can restart the ADI sync service. If you want to change the sync interval, you can change the information in the sync-interval field of your ADIsync.conf file.
2. Can I limit what data syncs to my KMSAT account from Active Directory? How do I change which Active Directory fields ADI pulls data from?
Yes, you can limit the data that syncs to your KMSAT account. In your <domain>.conf file, you will see an area with the settings below:
[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"
If you don't want ADI to pull data for a field, you can leave the field blank or delete the field that is listed between the double quotation marks. Removing fields will not overwrite the existing data for those fields. If you want ADI to pull data from a different field, you can change the field between the double quotation marks to a different field where your user information exists. Fields are case-sensitive and must match the attribute name in your AD.
3. How do I sync my AD groups with my KMSAT groups?
The groups that sync to KMSAT are based on security groups and distribution groups in Active Directory. If you want to sync AD groups with your KMSAT account, you can add those groups to the [sync.groups] section of your <domain>.conf file. To add AD groups to your <domain>.conf file, you can use one of the methods below:
- If the groups you want to sync are in one or more OUs, enter the OUs into the includedOUs field of your <domain>.conf file.
- If you want to sync specific groups, enter the groups into the includedGroups field of your <domain>.conf file.
For more information about syncing users and groups, see the Defining Which OUs, Groups, and Users to Sync section of our Active Directory Integration (ADI) Configuration Guide.
4. How often can I send a sync request for ADI API?
If test mode is enabled for your account, you can start and stop the ADI service as frequently as you'd like. Once you have turned off test mode, your ADI API sync request frequency is limited to once every six hours.
5. How can I exclude expired AD accounts from my ADI sync?
To exclude AD accounts from syncing to your KMSAT account based on the expiration date of the accounts, follow the steps below:
- Identify a date that expired accounts will be excluded before or on.
- Convert the date to Integer8 syntax.
- If you need help converting the date to Integer8 syntax, you can use the conversion tools that are linked below:
- For an example of Integer8 syntax, see the table below:
Standard Format Integer 8 Syntax 5/21/2017 10:41:52 AM Eastern Time (ET) 131398513120000000
- If you need help converting the date to Integer8 syntax, you can use the conversion tools that are linked below:
- Add the converted date to the filter_users_by_ou and filter_users_by_group fields in your <domain>.conf file. For example, see the section below, where XXXXXXXXXXXXXXXXXX represents the date in Integer8 syntax:
filter_users_by_ou =
"(&(|(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 =
"(&(|(accountExpires>=XXXXXXXXXXXXXXXXXX)(accountExpires=0))(objectCategory=person)(objectClass=user)(mail=*)(!userAccountControl:1.2.840.113556.1.4.803:=2)(!cn=HealthMailbox*)(!cn=SystemMailbox*)(|{DYNAMIC_CONTENT}))"
6. How can I exclude AD accounts that haven't logged on in the past XX number of days in my sync?
You can exclude AD user accounts from syncing to your KMSAT account based on the lastLogonTimeStamp AD account attribute.
To exclude users from your sync based on a last login date, follow the steps below:
- Identify a date that you want to use as the last login date limit.
- Convert the date to Integer8 syntax.
- If you need help converting the date to Integer8 syntax, you can use the conversion tools that are linked below:
- For an example of Integer8 syntax, see the table below:
Standard Format Integer 8 Syntax 5/21/2017 10:41:52 AM Eastern Time (ET) 131398513120000000
- Add the converted date to the filter_users_by_ou and filter_users_by_group fields in your <domain>.conf file. For example, see the section below, where XXXXXXXXXXXXXXXXXX represents 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}))"
7. If I add a user to a KMSAT group and the user is not in that AD group, will the user be removed from the KMSAT group during the next sync?
Yes, if the group is synced with your AD account. For example, if you add a user to a KMSAT group that is not synced with your AD account, the user will remain in the KMSAT group unless you remove the user. You can add both AD-managed and non AD-managed users to the KMSAT group. However, if you sync the KMSAT group with an AD group, the group will be managed by AD for AD-managed users. You can also add non AD-managed users to AD-managed groups, but the AD sync won’t affect those users.
8. Many user accounts in my Active Directory are disabled. Will these user accounts sync to my KMSAT account?
No, users with disabled AD accounts will not sync to your KMSAT account. However, if you want to sync disabled manager accounts, you can modify the LDAP filters in the <domain>.conf file.
9. Why can't I sync contact objects with ADI?
ADI can only sync users or groups that are members of your Active Directory domain. Contact objects typically represent external users. Often, the primary purpose of contact objects is to appear in your organization's email address book so your users can send emails to external users. Contact objects are not part of your domain, and you cannot assign permissions to them.
10. Will my users' passwords sync to my KMSAT account?
No. ADI does not query your AD passwords, so no passwords will sync to your KMSAT account.
11. I'm using Carbon Black Cloud and am having issues with my KnowBe4 ADI. What should I do?
If you use Carbon Black Cloud and are having issues with our ADI, please this article from Carbon Black Cloud.
Troubleshooting
For troubleshooting information about ADI, see the questions below:
1. How do I enable detailed logging to see which errors may be impacting my import?
3. I'm getting a "No valid email addresses" error next to several users. What does this error mean?
4. I'm using the EU instance of KMSAT, and my sync failed. What should I do?
7. I'm getting a "Not enough space" error after an ADI sync attempt. How can I resolve this error?
8. Is there a file that I can download that shows sync errors and details?
9. Why weren't my OUs added to KMSAT as groups during my ADI sync?
10. Why can't the ADI tool find any email addresses for my users?
1. How do I enable detailed logging to see which errors may be impacting my import?
Navigate to your ADISync folder, and open your ADISync.conf file. In the file, change the logging level from log-level = "ERROR" to log-level = "TRACE". The next time the sync occurs, you will be able to see more detailed information about what actions may have occurred to cause errors with your sync. To view your error logs, navigate to the KnowBe4\ADISync\logs folder.
2. I am having difficulties with including or excluding specific users and groups from the sync. How do I fix this issue?
This issue may occur because the person who is attempting to sync is not a domain admin. Domain admins will typically have the necessary permissions for including and excluding users and groups, but you can use any account that has permission to query all data. If you do not have access to an account with the necessary permissions, you can create a service account with the Read all user information and Read all inetOrgPerson information permissions. To learn how to create an ADI service account, see our How to Create an ADI Service Account in Active Directory article.
If you need to change the user that the ADI sync service is using to connect to your domain controller, follow the instructions below:
- Navigate to your ADIsync folder.
- Delete the <domain>.dat file from the folder.
- Open an elevated command prompt window.
- Navigate to your ADIsync folder in the command prompt.
- Enter ADIsync.exe config into the command prompt.
3. I'm getting a "No valid email addresses" error next to several users. What does this error mean?
This error typically occurs if all of the domains in your Active Directory are not added to your KMSAT account.
To learn how to add domains to your KMSAT account, see our How to Add and Verify Allowed Domains article. After you add all of your domains and the next sync occurs, the "No valid email addresses" error should be resolved.
If you need further assistance, contact our support team.
4. I'm using the EU instance of KMSAT, and my sync failed. What should I do?
You should resolve this issue by updating the post-URL in your ADIsync.conf file. The default location for the ADIsync.conf file is Program Files\KnowBe4\ADISync. Currently, the post-URL is most likely "https://training.knowbe4.com/api/v1/ldap/user_upload". You will need to change the post-URL to "https://eu.knowbe4.com/api/v1/ldap/user_upload". Then, save the ADIsync.conf file, and restart the ADI sync service.
If your error persists or the post-url was already correct, contact our support team.
5. I don't have edit permissions to save my <domain>.conf file, so I can't configure my LDAP filter. What should I do?
If you are unable to give yourself edit permissions, request that your IT team or administrator gives you permission to edit the ADIsync folder.
To give yourself edit permissions for the ADISync folder, follow the steps below:
- Navigate to your ADIsync folder (Program Files/KnowBe4\ADIsync).
- Right-click the ADIsync folder, and select Properties.
- Select the Security tab.
- Click the Edit button.
- Click the Add button.
- Enter your username, and click the Check Names button.
- If your account is showing correctly after clicking Check Names, click the OK button.
- Under your username, click the check box next to Full control to give yourself full permissions for the ADIsync folder.
- In the ADIsync Properties window, click the OK button. Now, you should have the permissions you need to edit the <domain>.conf file.
6. I'm getting a "Cowardly refusing to synchronize" error after an ADI sync attempt. How can I fix this?
This error typically occurs if you did not specify the location where ADI can pull your users from. You can specify this location in the [sync.users] section of your <domain>.conf file. For more information, see the Defining Which OUs, Groups, and Users to Sync section of our Active Directory Integration (ADI) Configuration Guide.
If you need further assistance, contact our support team.
7. I'm getting a "Not enough space" error after an ADI sync attempt. How can I resolve this error?
First, make sure that you meet the ADI prerequisites that are listed in the Prerequisites section of our Active Directory Integration (ADI) Configuration Guide. If you meet the prerequisites and are still getting this error, we recommend that you install the latest version of Windows Server 2019.
If Windows Server 2019 is already installed or installing Windows Server 2019 does not resolve this error, contact our support team.
8. Is there a file that I can download that shows sync errors and details?
Yes. You can download a text file that includes information about all of the sync changes and detailed information about any errors. You can download this file from the sync's Details page. To navigate to this file, follow the instructions below:
- From your KMSAT navigation panel, navigate to Users > Provisioning.
- Click the Details button that is in the same row as the sync.
- Near the top-right corner of the page, click the Sync and Error Details link.
For more information about the Details page, see our How to Use the Provisioning Tab article.
9. Why weren't my OUs added to KMSAT as groups during my ADI sync?
OUs cannot be added as groups to KMSAT. Only security and distribution groups will be added or synced as groups in KMSAT. When you include OUs in the [sync.groups] section of your <domain.conf> file, only groups that are included in that OU will be added and synced to KMSAT.
10. Why can't the ADI tool find any email addresses for my users?
ADI finds your users' email addresses in the proxyAddresses field of your Active Directory. If you are using a mail server other than Microsoft Exchange or Microsoft 365, the proxyAddresses field is most likely blank.
To solve this issue, you will need to change the field where KMSAT pulls email addresses from in your Active Directory, such as the mail attribute field. To learn how to change this field, see the How Do I Change Where to Pull the Email Addresses from Active Directory? section of our Active Directory Integration (ADI) Configuration Guide.
If you need further assistance, contact our support team.
Comments
0 comments
Article is closed for comments.