Syncing Information Through Active Directory

See below for detailed information about how to sync information to KnowBe4 through Active Directory (AD).

Jump to:
Sync Users by Inclusion/Exclusion of OU, Group, or Specific User (Required)
Sync Groups by Inclusion/Exclusion of OU or Group (Optional)
Syncing Other User Information to KnowBe4 

Sync Users by Inclusion/Exclusion of OU, Group, or Specific User (Required)

The following options are for identifying user objects to be synchronized and are located under the [sync.users] portion of the .conf file:

includedOUs - List of OUs that will be searched for users.

• Specified OUs are recursed and all mail-enabled accounts that are not disabled will be found. For example, if "Users" is specified, then any qualifying user objects within that OU or underlying OUs (and underlying OUs under those OUs, and so on) will be included.
  Note: Using this field will not search for users within groups, within the specified OUs. Use the includedGroups field (below) to sync users from security or distribution groups.
• If you want to specify an OU that is beneath a root level OU, you must use reverse syntax separated by a forward slash. For example, if there is a root OU called "All Users" and beneath that there is an OU called "Accounting", you would format this as "Accounting/All Users".
• Additionally, if multiple OUs are to be specified they need to be enclosed in double quotes and separated by commas, all of which is encapsulated in brackets.
• For example: includedOUs = ["Accounting/All Users","Development/All Users"]

excludedOUs - List of OUs that will be searched for users that will be excluded.

• If there are excluded users found, they will cancel out any OU users that are specified for inclusion.
• The syntax for the excludedOUs is the same as for includedOUs. 
• For example: excludedOUs = ["Contractors/Development/All Users"]

includedGroups = List of groups that will add users that are either directly or indirectly members of the specified Active Directory security or distribution groups.

• For example, if there is a group called "Accounting" which contains 4 user accounts and a group called "Finance", then all 4 user accounts in "Accounting" will be included, as well as any members of the "Finance" group.
• Users found in this manner will override users defined for exclusion by "excludedOUs".
• Multiple groups need to have each group enclosed in double quotes and separated by commas, all of which must be encapsulated in brackets.
• For example: includedGroups = ["Accounting","Human Resources"]

excludedGroups - List of groups that will exclude users that are either directly or indirectly members of the specified Active Directory security or distribution groups.

• If there are users found in this configuration, they will cancel out users that are found in either includedOUs or includedGroups. The syntax is the same as includedGroups.
• For example: excludedGroups = ["Contract Employees"]

includedUsers - List of users to be explicitly included.

• Users are specified using "username@domain.com" syntax and multiple users may be specified using syntax similar to prior options.
• Any users specified in this option will override any prior exclusion by group or OU.
• For example: includedUsers = ["mwhite@knowbe4.com"]

excludedUsers - List of users to be explicitly excluded.

• This uses the same "username@domain" syntax as includedUsers and multiple users may be specified.
• Any users specified in this option will be excluded regardless of any inclusion rules.
• For example: excludedUsers = ["jsmith@knowbe4.com","mjones@knowbe4.com"]

Back to Top

Sync Groups by Inclusion/Exclusion of OU or Group (Optional)

After criteria for user synchronization has been defined (this is required), one may optionally set groups for synchronization. These are AD groups which will show up in the KnowBe4 console as groups, which you can target as desired with Phishing or Training campaigns. If a user is directly or indirectly a member of a group in AD then they will directly be a member of that group in the KnowBe4 console (NOTE: KnowBe4 does not support nested groups).

It is important to note that only users found in the earlier process will have their membership shown in these synchronized groups. If a group is specified for synchronization but no synchronized users are members (directly or indirectly) then the group will not be synchronized.

The following options are for identifying groups to be synchronized and are located under the [sync.groups] portion of the .conf file:

includedOUs - A list of OUs that will be recursively searched for security or distribution groups.

• Only groups specifically found under the specified OU structure will be included.
• Syntax is similar to earlier OU syntax, in that multiple OUs may be specified, with each enclosed by double quotes, separated by commas, and entirely encapsulated in brackets.
• For example: includedOUs = ["Accounting/All Users","Development/All Users"]

excludedOUs - A list of OUs that will be recursively searched for security or distribution groups that will not be synchronized.

• Syntax is the same as other OU options.
• For example: excludedOUs = ["Contractors/Development/All Users"]

includedGroups - A list of specific security or distribution groups to be synchronized.

• Any groups specified will be synchronized and members (direct or indirect) that are included in the user sync will be populated.
• This option overrides any excluded groups from the earlier "excludedOUs" option under sync.groups.
• For example: includedGroups = ["Sales","Accounting"]

excludedGroups - A list of specific groups to be excluded from synchronization.

• Any groups specified will not be synchronized.
• This option overrides any groups specified in includedOUs or includedGroups specified in sync.groups.
• For example: excludedGroups = ["Consultants"]

Once the filter criteria has been set, save the file. You may need to give yourself appropriate write permissions to do so.

Back to Top

Syncing Other User Information to KnowBe4

In the <domain>.conf file are the fields listed below. By default, the fields will automatically populate the user information fields in your KnowBe4 console as defined in Active Directory (AD). You have the option to limit the data that Active Directory syncs to KnowBe4. For more information on how to do this, see this question on our FAQ: Active Directory Integration (ADI) article. 

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

How Do I Change the Field Values?

You can change the data in the quotes to reflect the proper field in AD where your user information exists. Keep in mind, this field is case sensitive and should be edited with caution.

A blank field indicates that there is no matching field in AD. This is where you can decide which field you'd like to pull by adding a value between the quotation marks.

How Do I Prevent a Field from Syncing?

If you prefer not to import certain fields, delete the value between the quotation marks to the right of the equal sign (do not delete the quotation marks or the whole line of text - only delete what is between the quotation marks). If you delete the whole line, the service will automatically add it back in and sync what you don't want to sync.

Sync Use Cases

Below are example use cases for how you can control which AD fields sync to your KMSAT console:

If you want to self-manage all custom fields in your console, you have the option to keep those fields from being included in your AD sync. You can do this by including the following in your .conf file:

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

Notice that all of the custom fields are blank, or have all data between the quotation marks removed.

If you would like to sync the department of your users, but not their division or location, you can do so by including the following in your .conf file:

[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"
phone-number = "telephoneNumber"
title = "title"

Notice that the division and location fields are blank, or have all data between the quotation marks removed.

If you want to include all fields in your AD sync, you can do so by customizing the following in your .conf file:

[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 = “5555555555“
organization = "o"
phone-number = "telephoneNumber"
title = "title"

Notice that all fields to be synced have a value between the quotation marks.

Back to Top