If you would like to manage users through Active Directory Integration (ADI), you will need to define which users and groups to sync to your KSAT console. To define which users and groups to sync, you can edit the ADI configuration (CONF) file that you download during the configuration process.
In this article, you'll learn how to edit your CONF file to sync specific users, groups, and user information. For general information about ADI, see our Active Directory Integration (ADI) Configuration Guide. If you would prefer to use SCIM, see our SCIM Configuration Guide. If you have purchased Student Edition, you can set the User Type KSAT field by using the user-role field in the .conf file.
Defining Which Users to Sync
In this section, you’ll learn how to edit your CONF file to define which users to sync to your KSAT console from your AD. These AD users will populate as users in your KSAT console. You will need to sync specific users before you can sync groups.
To edit your CONF file to define which users you would like to sync, follow the steps below:
-
Open your ADI CONF file in a text editor. For more information about finding your CONF file, see our Active Directory Integration (ADI) Configuration Guide.
- Edit the following fields in the [sync.users] section of the file. For more information about these fields, see the table below.
Field Name |
Field Description |
includedOUs |
In this field, enter the list of OUs that should be searched to sync your users.
|
excludedOUs |
In this field, enter the list of OUs that will be searched for users that will be excluded.
|
includedGroups |
In this field, enter the list of groups that users should be synced from. These groups must be either AD security groups or distribution groups.
|
excludedGroups |
In this field, enter the list of groups that will exclude users that are members of the specified AD security or distribution groups.
|
includedUsers |
In this field, enter the list of users who should be explicitly included.
|
excludedUsers |
In this field, enter the list of users who should be explicitly excluded.
|
If you would like to sync groups, see the Defining Which Groups to Sync section below.
Defining Which Groups to Sync
After you have defined the criteria for syncing specific users, you can also edit your CONF file to define the criteria for any AD groups that you want to sync. These AD groups will populate as groups in your KSAT console.
If a user is a member of a group in AD, then they will be a member of the corresponding group in your KSAT console. KnowBe4 does not support groups within groups, or nested groups.
It’s important to note that you must sync users first before they can be included in synced groups. If you would like to sync a group but the group does not include any synced users, the group will not sync.
To edit your CONF file to define the groups that you would like to sync, follow the steps below:
- Make sure that you have synced specific users. For more information, see the Defining Which Users to Sync section above.
- Edit the following fields in the [sync.groups] section of your CONF file. For more information about these fields, see the table below.
Field Name |
Field Description |
includedOUs |
In this field, enter the list of OUs that you would like to search to sync your security or distribution groups.
|
excludedOUs |
In this field, enter the list of OUs that you would like to search for security or distribution groups that will not be synced.
|
includedGroups |
In this field, enter the list of specific AD security or distribution groups that you would like to sync.
|
excludedGroups |
In this field, enter the list of specific groups that you would like to exclude from the sync.
|
Once you have edited these fields to your liking, save the CONF file. To save the file, you will need write permissions.
Syncing Other User Information
Once you have selected the specific users and groups that you would like to sync, you can also edit your CONF file to define which user information syncs from your AD account to your KSAT account. To define which user information to sync, you can edit the [sync.fields] section of the file. By default, the fields in the [sync.fields] section will automatically populate the user information fields in your KSAT console with the information defined in your AD.
To include the field in AD where your user information exists, you can edit the value in the quotation marks for each field. If a field is blank, there is no matching field in AD. You can define which AD fields you would like to sync to KSAT by manually adding a value in between the quotation marks for each field.
If you would like to prevent specific fields from syncing, you can delete the value in the quotation marks for that field. However, make sure that you do not delete the quotation marks or the whole line of text. If you delete the whole line of text, AD will automatically add the line of text back to the field and sync the value.
For a list of the default fields available in the [sync.fields] section of your CONF file, see 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"
out-of-office-end = ""
phishing-language = "preferredLanguage"
phone-number = "telephoneNumber"
training-language = "preferredLanguage"
title = "title"
user-role = ""
SecurityCoach Fields
If you enabled SecurityCoach fields when configuring ADI, eight additional fields will display in the [sync.fields] section of your CONF file. These fields can be used to automatically map KSAT users to SecurityCoach events. Additionally, you can use these fields when mapping users to identifiers in SecurityCoach. When this information syncs, it will be added to the SecurityCoach Fields section of the User Information page.
For a list of these SecurityCoach fields and their default mappings, see below:
company-name = "company"
country = "co"
employee-type = "employee type"
hostname = "userWorkstations"
last-password-change-date-time = "pwdLastSet"
mail-nickname = "mail"
on-premises-sam-account-name = "sAMAccountName"
on-premises-security-identifier = "objectSid"
user-principal-name = "userPrincipalName"
Sync Use Cases
Below are example use cases for controlling which AD fields sync to your KSAT console.
Use Case: Exclude Fields from Your AD Sync
If you would like to manage custom fields in your KSAT console, you can exclude those fields from your AD sync. This exclusion applies to only custom fields. If you try to leave fields blank other than the custom fields, their values will be cleared in KSAT.
To exclude custom fields from your AD sync, include the following syntax in the [sync.fields] section of your CONF file. In the syntax below, all of the custom fields are blank or the values in the quotation marks have been removed:
[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" out-of-office-end = ""
phishing-language = "preferredLanguage"
phone-number = "telephoneNumber"
title = "title"
training-language = "preferredLanguage"
user-role = ""
Use Case: Exclude Users' Divisions and Locations
If you would like to sync your users’ departments but not their divisions or locations, include the following syntax in the [sync.fields] section of your CONF file. In the syntax below, the division and location fields are blank, or the values in the quotation marks have been removed:
[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 = ""
manager = "manager"
mobile-number = ""
organization = "o" out-of-office-end = ""
phishing-language = "preferredLanguage"
phone-number = "telephoneNumber"
title = "title"
training-language = "preferredLanguage"
user-role = ""
Use Case: Include All Fields in Your AD Sync
If you would like to include all fields in your AD sync, include the following syntax in the [sync.fields] section of your CONF file. In the syntax below, all fields have a value in quotation marks:
[sync.fields]
comment = “This is a comment!“
custom-date-1 = “This is my custom-date-1 field.“
custom-date-2 = "This is my custom-date-2 field."
custom-field-1 = "This is my custom-field-1”
custom-field-2 = "This is my custom-field-2.”
custom-field-3 = "This is my custom-field-3”
custom-field-4 = "This is my custom-field-4”
department = "department"
division = “division”
employee-number = "employeeNumber"
employee-start-date = "whenCreated"
first-name = "givenName"
last-name = “last-name”
location = "physicalDeliveryOfficeName"
manager = "manager"
mobile-number = “mobile“
organization = "o" out-of-office-end = ""
phishing-language = "preferredLanguage"
phone-number = "telephoneNumber"
title = "title"
training-language = "preferredLanguage"
user-role = ""