Active Directory Integration

Share

Is this article helpful?

Last updated:

Edit Your CONF File for Active Directory Integration (ADI)

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:

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

  2. Edit the following fields in the [sync.users] section of the file. For more information about these fields, see the table below.
Note: These fields are case-sensitive.
Important: If your organizational units (OUs) or group names contain characters that are not part of the standard English alphabet, replace the quotation marks (") with single quotation marks ('). Escape special characters such as commas (,), number signs (#), and plus signs (+) by using a double backslash (\\). For more information, see our How to Use Escape Characters with Active Directory Integration article.
Field Name

Field Description
includedOUs

In this field, enter the list of OUs that should be searched to sync your users.

  • The specified OUs will be searched for any users that have mail-enabled turned on. 
    Important: This field will not include users within groups, within the specified OUs. To sync users within these groups, see the information for the includedGroups row below.
  • If you would like to specify an OU that is beneath another OU, you must write the name of the OU location using reverse syntax and separate the file path with a forward slash. For example, if you would like to specify an OU called “Accounting” that is under an OU called “All Users”, you would format the syntax as "Accounting/All Users".
  • If you would like to include multiple OUs in your list of included OUs, you will need to format this text in a specific way. You will need to enclose the OUs in quotation marks, separate the OUs with commas, and enclose the OUs in brackets. For an example of the syntax for this field, see below:
    • includedOUs = ["Accounting/All Users","Development/All Users"]
excludedOUs

In this field, enter the list of OUs that will be searched for users that will be excluded.

  • If excluded users are found during the search, they will override any corresponding OU users that were going to be included in the sync.
  • For an example of the syntax of this field, see below:
    • excludedOUs = ["Contractors/Development/All Users"]
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.

  • Users found the includedGroups field will override any corresponding users defined in the excludedOUs field.
  • If you include multiple groups in this field, make sure that you format the syntax correctly. You will need to enclose the groups in quotation marks, separate the groups with commas, and enclose the groups in brackets. For an example of the syntax for multiple groups, see below:
    • includedGroups = ["Accounting","Human Resources"]
excludedGroups

In this field, enter the list of groups that will exclude users that are members of the specified AD security or distribution groups.

  • If excluded users are found during this search, they will override corresponding users that are found in either includedOUs or includedGroups.
  • For an example of the syntax for this field, see below:
    • excludedGroups = ["Contract Employees"]
includedUsers

In this field, enter the list of users who should be explicitly included.

  • Users specified in this field will override any corresponding users in the excludedGroups field or the excludedOUs field.
  • Specify each user by entering their email address. You can specify as many users as you would like.
  • For an example of the syntax for this field, see below:
    • includedUsers = ["user@example.com"]
excludedUsers

In this field, enter the list of users who should be explicitly excluded.

  • Users specified in this field will be excluded, regardless of any other inclusion rules.
  • Specify each user by entering their email address. You can specify as many users as you would like. For an example of the syntax for this field, see below:
    • excludedUsers = ["user@example.com","user2@example.com"]

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.

Important: The only types of groups that will sync to your KSAT console are security groups and distribution groups. Groups within included OUs will be added or synced as groups in the console. However, the OU itself will not be synced with the console.

To edit your CONF file to define the groups that you would like to sync, follow the steps below:

  1. Make sure that you have synced specific users. For more information, see the Defining Which Users to Sync section above.
  2. Edit the following fields in the [sync.groups] section of your CONF file. For more information about these fields, see the table below.
Note: These fields are case-sensitive.
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.

  • Only groups found under the specified OU will be added as groups in your KSAT console.
  • If you are including multiple OUs, make sure that you format the syntax correctly. You will need to enclose the OUs in quotation marks, separate the OUs with commas, and enclose the OUs in brackets. For an example of the syntax for multiple OUs, see below:
    • includedOUs = ["Accounting/All Users","Development/All Users"]
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.

  • For an exampled of the syntax for this field, see below:
    • excludedOUs = ["Contractors/Development/All Users"]
includedGroups

In this field, enter the list of specific AD security or distribution groups that you would like to sync.

  • When these groups sync, only users that you included in the users sync will be added to the corresponding KSAT group. This option overrides any excluded groups from the excludedOUs field in the [sync.groups] section.
  • For an example of the syntax for this field, see below:
    • includedGroups = ["Sales","Accounting"]
excludedGroups

In this field, enter the list of specific groups that you would like to exclude from the sync.

  • This option overrides any groups in the includedOUs field or the includedGroups field in the [sync.groups] section.
  • For an example of the syntax for this field, see below:
    • excludedGroups = ["Consultants"]

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.

Note: User phishing and training languages are synced from the AD preferredLanguagefield by default. You can modify that AD field or remove these fields from being synced by following the Sync Use Cases section below.
Tip: You also have the option to limit the data that your AD syncs to your KSAT console. For more information, see the Syncing Information section of our Active Directory Integration (ADI) FAQ article.

For a list of the default fields available in the [sync.fields] section of your CONF file, see below:

Note: These fields are case-sensitive.

[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. SecurityCoach fields on the User Information page

For a list of these SecurityCoach fields and their default mappings, see below:

Note: These fields are case-sensitive.

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 = ""

Was this article helpful?

8 out of 11 found this helpful

Can't find what you're looking for?

Contact Support