Active Directory Integration

Share

Is this article helpful?

FAQ: Active Directory Integration (ADI)

In this article, you can find frequently asked questions about using Active Directory Integration (ADI) to integrate your Active Directory (AD) with your KSAT 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 KSAT, see our Active Directory Integration (ADI) Configuration Guide.

General Information

For general information about ADI, see the questions below:

  1. What is the advantage of integrating Active Directory with my KSAT 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 KSAT account, will any changes happen in my Active Directory?
  6. If I have multiple domains in my AD account and I'm importing users into my KSAT account with ADI, how does ADI determine which email address to use for my 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?

1. What is the advantage of integrating Active Directory with my KSAT account?

You can use ADI to manage your user list in KSAT through Active Directory. The changes that you make to your AD account will affect your KSAT account at each sync. For example, if you archive a user in your AD account, the ADI sync will archive that user in your KSAT account.

Additionally, you can specify which user information is automatically synced into your KSAT 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 KSAT. 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:

  1. From your computer, navigate to the Config folder: C:\ProgramData\KnowBe4\ADI Sync\Config
  2. Delete the .dat file from the folder.
  3. Open an elevated command prompt window.
  4. Navigate to the C:\Program Files\KnowBe4\ADI Sync folder in the command prompt.
  5. Enter "adisync.exe config" into the command prompt.
  6. 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 KSAT 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 KSAT account, will any changes happen in my Active Directory?

No. While the changes you make in Active Directory will affect your KSAT account, the changes you make in your KSAT account will not affect Active Directory.

6. If I have multiple domains in my AD account and I'm importing users into my KSAT 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?
  4. How do I manage my ADI if I have multiple source domains but I want to sync everything to a single KSAT account? Or, how do I sync everything to one KSAT account if I have multiple domains and multiple domain controllers that do not communicate with each other?
  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?
  6. My AD users and groups are not organized how I'd like them to be organized in my KSAT account. What should I do?
  7. My organization has a proxy or firewall in place. How can I connect to ADI successfully?
  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?
  9. What happens if I enable the Show Group Domain setting in my KSAT Account Settings?
  10. My KSAT 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. 

Important:If you enable LDAPS, you will need to set the use-ssl field to true in your <domain>.conf file.

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 KSAT account? Or, how do I sync everything to one KSAT 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 KSAT 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 KSAT account. For a successful installation, you'll need to install ADI on a separate machine for each domain that you want to sync with.

6. My AD users and groups are not organized how I'd like them to be organized in my KSAT 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 KSAT groups to the OU. For example, if you have a KSAT 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 KSAT 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.

Important:ADI does not support nested groups, which are groups that are members of other groups. However, ADI does support nested users, which are users that are members of nested groups. 

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. Where is my information being sent when using ADI sync?

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 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 KSAT Account Settings?

When you enable the Show Group Domain setting, ADI will add your domain name to your AD-synced KSAT groups. For example, a KSAT 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 KSAT account is on test mode. What is test mode, and when should I turn it off?

After you set up ADI, your KSAT 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 KSAT account with Active Directory. To view this preview, log in to your KSAT 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 KSAT 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 KSAT account?
  2. Can I limit what data syncs to my KSAT account from Active Directory? How do I change which Active Directory fields ADI pulls data from?
  3. How do I sync my AD groups with my KSAT 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?
  7. If I add a user to a KSAT group and the user is not in that AD group, will the user be removed from the KSAT group during the next sync?
  8. Many user accounts in my Active Directory are disabled. Will these user accounts sync to my KSAT account?
  9. Why can't I sync contact objects with ADI?
  10. Will my users' passwords sync to my KSAT 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 KSAT account?

Yes. By default, the ADI sync service will sync your AD account to your KSAT 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.

Note:The minimum sync interval is six hours (6h0m0s).

2. Can I limit what data syncs to my KSAT 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 KSAT 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.

Note:The mobile-number field in your <domain>.conf file will be blank because there is not a mobile-number field in Active Directory. However, you can enter the name of another field you want to pull the mobile-number data from. The two custom-date fields in your <domain>.conf file must follow the mm/dd/yyyy format.

3. How do I sync my AD groups with my KSAT groups?

The groups that sync to KSAT are based on security groups and distribution groups in Active Directory.  If you want to sync AD groups with your KSAT 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.
Important:The users who are members of the groups included in the [sync.groups] section must also be included in the [sync.users] section of your <domain>.conf file. For example, if your AD group has 100 members and only 85 of those members are included in the [sync.users] field, only the 85 users will be added to the group in your KSAT account. 

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 KSAT account based on the expiration date of the accounts, follow the steps below:

  1. Identify a date that expired accounts will be excluded before or on.
  2. Convert the date to Integer8 syntax.
  3. 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}))"
Note:If you want to continuously exclude expired accounts, you will need to manually update the date in the <domain>.conf file. For example, if you initially entered 11/20/2021 for the date and more accounts have expired since then, you will need to update the date in the <domain>.conf file to account for the newly expired accounts. 

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 KSAT account based on the lastLogonTimeStamp AD account attribute.

To exclude users from your sync based on a last login date, follow the steps below:

  1. Identify a date that you want to use as the last login date limit. 
  2. Convert the date to Integer8 syntax.
  3. 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}))"
Note:You will need to update this timestamp often. For example, if you want to exclude accounts that haven't logged in for 90 days, you will need to update the timestamp every 90 days so that the data is 90 days before the current date.

7. If I add a user to a KSAT group and the user is not in that AD group, will the user be removed from the KSAT group during the next sync?

Yes, if the group is synced with your AD account. For example, if you add a user to a KSAT group that is not synced with your AD account, the user will remain in the KSAT group unless you remove the user. You can add both AD-managed and non AD-managed users to the KSAT group. However, if you sync the KSAT 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 KSAT account?

No, users with disabled AD accounts will not sync to your KSAT 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 KSAT account?

No. ADI does not query your AD passwords, so no passwords will sync to your KSAT 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 see 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?

2. I am having difficulties with including or excluding specific users and groups from the sync. How do I fix this issue?

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 KSAT, and my sync failed. What should I do?

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?

6. I'm getting a "Cowardly refusing to synchronize" error after an ADI sync attempt. How can I fix this?

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 KSAT 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?

To enable detailed logging, follow the steps below:

1. Open the installation folder: C:\Program Files\KnowBe4\ADI Sync.
2. Double-click the support_enable_logging.bat file.
3. In the pop-up window that opens, click Yes to allow the Troubleshooter app to make changes to your device.
4. When the Command Prompt window displays the Press any key to continue... message, press a key on your keyboard.

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 C:\ProgramData\KnowBe4\ADI Sync\DebugLogs folder.

If you continue to experience issues with your ADI sync, please contact our support team.

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:

  1. Navigate to your C:\ProgramData\KnowBe4\ADI Sync\Config folder. 
  2. Delete the <domain>.dat file from the folder.
  3. Open an elevated command prompt window.
  4. Navigate to your C:\Program Files\KnowBe4\ADI Sync folder in the command prompt.
  5. 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 KSAT account.To learn how to add domains to your KSAT 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.

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:

  1. Navigate to your ADIsync folder (Program Files/KnowBe4\ADIsync).
  2. Right-click the ADIsync folder, and select Properties.
  3. Select the Security tab.
  4. Click the Edit button. 
  5. Click the Add button. 
  6. Enter your username, and click the Check Names button. 
  7. If your account is showing correctly after clicking Check Names, click the OK button.
  8. Under your username, click the check box next to Full control to give yourself full permissions for the ADIsync folder.
  9. In the ADI Sync 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 "No users found for synchronization" 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.

Note:If your users are split between multiple domains, you will need to verify that this location is specified in the [sync.users] section of each domain's <domain>.conf file. 

If you need further assistance, contact our support team.

7. 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:

  1. From your KSAT navigation panel, navigate to Users > Provisioning.
  2. Click the Details button that is in the same row as the sync.
  3. 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.

8. Why weren't my OUs added to KSAT as groups during my ADI sync?

OUs cannot be added as groups to KSAT. Only security and distribution groups will be added or synced as groups in KSAT. 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 KSAT. 

9. 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 KSAT 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.

Was this article helpful?

13 out of 16 found this helpful

Can't find what you're looking for?

Contact Support