You are here:

Active Directory Settings

If your organization uses Microsoft^® Active Directory^® to manage network user accounts, you can configure PolicyTech to use Active Directory (AD) for the following purposes:

Initial user import
User list maintenance (daily synchronization)
User login

Note: The alternatives to using AD to create and maintain the PolicyTech user list are to define and maintain users manually or to export a user list from another database and import that list into PolicyTech. For details, see User Setup.

Considerations

There are many factors to consider when deciding how to configure PolicyTech to connect to and use AD. Some of the more common considerations include the following:

How much AD user information do you want pulled into PolicyTech user records?
If AD doesn't include all of the user data needed for PolicyTech user definitions, do you want to import the missing information from another database (see Importing Users from Another Database) or possibly add it to AD before syncing?
If users have already been defined in PolicyTech and any of those users also exist in AD, how do you ensure that the sync doesn't cause problems for those existing users?

Important: If users have already been defined in PolicyTech, please contact Customer Support at 888-359-8123 (toll-free in the U.S. and Canada) or 208-359-8123 so that a technician can walk you through the PolicyTech/Active Directory sync setup. This will help you avoid many possible issues that could result from syncing existing PolicyTech users with AD users. In addition, we highly recommend first configuring the AD sync on a test site with a restored backup of the production PolicyTech site, and then configuring the production site once you're sure the AD sync on the test site is working correctly.

If a user is deactivated or deleted in AD, do you also want that user deactivated or deleted in PolicyTech?
If you don't want all of the users in an AD domain synced with PolicyTech, how are you going to filter out those you don't want synced? Are the AD organizational units and containers set up in a way that accommodates efficient syncing of a specific set of users?
Do you know which organizational unit in the AD hierarchy to access so that all of the users you want synced with PolicyTech are contained in that organizational unit or in the ones below it?
Do you know which AD user credentials you're going to use to allow the PolicyTech sync process to access AD? Will you use a service account or a normal user?
Will your PolicyTech site be required to use SSL to authenticate to AD and, if so, is SSL set up correctly on the server hosting PolicyTech?

If, after reviewing the considerations above and the steps below, you have any questions, please contact Client Support at 888-359-8123 (toll-free in the U.S. and Canada) or 208-359-8123.

How the Sync Works

Knowing how the AD sync works can help you make decisions about how to set it up and when to run it. The following process is performed for each user profile that PolicyTech pulls from each AD domain you specify.

Attempt to match the AD GUID. PolicyTech users that are synced with AD users include an extra field of data in their PolicyTech user profile for storing the user's Globally Unique Identifier, or GUID, that is assigned by AD whenever an object is created. When you perform a sync, PolicyTech first checks to see if the AD user's GUID has already been added to a PolicyTech user profile.

If a matching GUID is found, the process skips to step 4 below.
If a matching GUID is not found, the process continues with step 2.

Note: Adding a GUID to a PolicyTech user profile can only be done by the AD sync feature. The GUID property is not available in the PolicyTech user profile in User Manager.

Attempt to match user names. If a matching GUID is not found, the sync next searches for a PolicyTech user name that is the same as the user logon name in the AD profile.

If a matching user name is found, the process skips to step 4.
If a matching user name is not found, the process continues with step 3.

Create a new PolicyTech user. If the sync finds no matching GUID or user name, it creates a new PolicyTech user and pulls at least the following properties from the AD user profile.

Note: Because these are the minimum required properties (except Domain) for creating a PolicyTech user, these properties are used regardless of whether or not they are enabled and mapped in the domain information you will later add in PolicyTech Login Settings.

PolicyTech User Property Added	From AD User Property
First Name	First name
Last Name	Last name
Username	User logon name (sAMAccountName)
Password	Random placeholder*
Unique Employee ID	AD GUID
Site	Mapped property in PolicyTech Login Settings^†
Department	Mapped property in PolicyTech Login Settings^†
Domain	Domain specified in PolicyTech Login Settings in the Organization Unit (OU) definition that included this user in the sync

*When AD sync is enabled, PolicyTech ignores whatever is stored in the Password field of the PolicyTech user profile and uses the password from the AD user profile instead. However, because the Password field is required, the sync places a random string in that field when creating a new user.

^†When you later specify the AD domains to sync with PolicyTech, you will be required to specify a default site for adding new users and will have the opportunity to map AD user properties to PolicyTech user properties. If you choose not to enable and map the site and department properties, users added during a sync will be assigned to the specified default site and to a department called Unassigned Department.

If necessary, create a new job title, department, or site. If the PolicyTech job title, department, or site property is mapped for the sync, PolicyTech will compare the property value in the AD user profile to the existing PolicyTech job titles, departments, or sites.

If the job title, department, or site already exists in PolicyTech, the process moves on immediately to step 5.
If the job title, department, or site doesn't exist in PolicyTech, then PolicyTech creates a new job title, department, or site and names it with the value from the corresponding AD user property.

Update mapped properties.

If the sync found a matching user, it compares the properties from the AD user profile to any corresponding PolicyTech user properties that you chose to include in the sync. If any properties don't match, PolicyTech overwrites the information in the PolicyTech user property with the information from the mapped AD user property.
If the sync created a new user, in addition to the required properties listed in step 3 above, it adds any optional properties you chose to include in the sync.

Important: As you can see from the process description above, the PolicyTech/AD sync feature will create new users, job titles, departments, and sites if they don't already exist in PolicyTech. If you add or modify any of these objects manually in PolicyTech, make sure the site reference IDs, department reference IDs, job title names, or user names exactly match the names of the corresponding objects in AD. If the PolicyTech object name varies even by a single character, such AVDept vs. AVDep, a new, duplicate object will be created in PolicyTech when AD is synced.

Enter Domain and Organizational Unit Information

Important: If you're not familiar with the AD setup in your organization, be sure to consult with or have your IT specialist or network administrator present when you perform the following steps.

PolicyTech uses the information you enter in the Domain Information form to communicate with AD and perform the user sync. This information is divided into three sections: Connection Settings, Synchronization Mapping, and Remote Domain.

Connection Settings

Click System Settings, click System / IT Settings, and then click Login Settings.
Click the Active Directory tab, and then click Add Domain.

You'll see one of the following messages, depending on whether your PolicyTech system is hosted by NAVEX Global (first message) or installed on your organization's premises (second message).

Do one of the following:

If your PolicyTech system is hosted by NAVEX Global, click Continue.
If you're prompted to back up your database, click Back Up Database, click OK, and then. when the backup is finished, click Close. Because backing up the database automatically logs you out of PolicyTech, log back in and repeat steps 1 and 2 above. Then, on this step, click Continue.

For Domain, type the name of a domain containing at least some of the users you want synced with PolicyTech.

Note: The domain name you type is only for identifying this domain definition in the PolicyTech Domains list. The actual distinguished domain name will be specified later when you add organizational units.

You now need to provide PolicyTech with the credentials of a user within the specified domain. We recommend creating a service account user within the domain to be used specifically for the purpose of enabling PolicyTech to log in to the domain with that user's credentials. The authorized user you create can be a simple user (does not need to be an administrator) with read access for all domain users and must be a member of the organizational unit that you'll be designating shortly.

Important: The authorized user should not be required to periodically change the account password, because the AD syncing capability in PolicyTech would be disabled as soon as the password expired. Someone would then need to change the AD password and update the authorized user password in PolicyTech.

Type the authorized user's name and password.
(Optional) An SSL (Single Sockets Layer) connection is not typically required between the PolicyTech website and the domain controller, but if the domain controller has been set up with a certificate to enable SSL, then you can select Require SSL to add a more sophisticated layer of encryption when the authorized user name and password are sent from PolicyTech to the domain controller.

Important:

If Require SSL is selected and SSL has not been enabled on the domain controller, the user sync will fail and users will not be able to log in to PolicyTech using AD credentials.
This option is NOT for configuring SSL for HTTP (not for enabling HTTPS).

For Authentication Type, select NTLM or Basic.

Note: NTLM is the native Microsoft^® authentication protocol and encrypts the user name and password as it is being sent. Basic authentication does not encrypt the user name and password and should be selected only if you have a specific need for doing so.

Select the PolicyTech site where you want AD users added and synced.

You must now set up at least one organizational unit (OU) for the specified domain (you can designate up to 10 OUs per domain). You can filter out unwanted users by selecting specific groups within the OU. PolicyTech will import and sync only those users that meet the filter conditions.

Click Add Organizational Unit (OU).

Type the OU's LDAP distinguished name that uniquely identifies it within AD. See About LDAP Distinguished Names below for details.

A filter string is included by default that returns only those AD users who are currently active. If desired, you can modify the filter string to further restrict returned users. See Filtering by Group Membership below for details.

Include Child OU's is selected by default, meaning that if the OU you specify contains other OUs, the users from those child OUs will also be synced. If you want only the OU specified and none of its child OUs included, click to clear the check box.

Important: The Include Child OU's option will NOT include sibling (parallel) or parent OUs.

Click Save.
In the Organizational Unit (OU) list, click the OU you just added, and then, below the list, click Test Connection to make sure all connection settings work.

Note: This tests all connection settings, including the user name and password you typed and the new OU definition.

(Optional) Repeat the steps above to add other OUs (up to 10 total).

Important:

Each OU you add runs as a separate LDAP query. Thus, the fewer OUs you add, the better the sync performance. For optimal performance, we recommend specifying the domain root as the only OU and then using a filter string to include or exclude specific user groups.
If you add multiple OUs, they must all be from the same domain.

Continue with the steps in the Synchronization Mapping section below.

About LDAP Distinguished Names

An LDAP distinguished name (DN) consists of a string of relative distinguished names (RDNs) separated by commas. In turn, an RDN consists of an attribute name followed by an equal sign and an object name. Which attribute precedes each object name depends on the object type: CN stands for common name; OU stands for organizational unit name; and DC stands for domain component (a domain name usually contains multiple components separated by periods, such as Sales.South.com).

The order of the RDNs within the DN is from the lowest level object name (CN=Users in the example above) to the domain root (DC=MyCompany,DC=com in the example above). Both OUs and containers—which are designated with the CN attribute—can contain users, so you need to make sure you use the correct attribute in each RDN. In an AD tree, objects with a plain folder icon ( in Windows Server 2012 or 2008; in Windows Server 2003) are containers and must use CN, while objects with a folder that has a user profile icon ( in 2008 and 2012) or book icon ( in 2003) superimposed are organizational units and must use the OU attribute.

For example, let's say that you want to add the Users OU selected in the AD tree shown below.

You would type the following DN:

OU=Users,OU=Human Resources,OU=San Diego,DC=MyCompany,DC=com

If you want to include all users in the San Diego OU, you would type the following and make sure that Include Child OU's were selected:

OU=San Diego,DC=MyCompany,DC=com

Filtering by Group Membership

Important: Providing a complete explanation of LDAP filters is not within the scope of this guide. The information below shows how to use some common methods for filtering by group.

The default filter when you add an OU is as follows:

(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(sAMAccountName=$logon))

The ampersand (&) is an AND operator that returns only those results that match all of the filters that follow it. The exclamation point (!) is a NOT operator that filters for the opposite of the filter following it. In plain English, the complete filter string above says to filter for AD objects that meet all of the following conditions:

Are assigned to the person category
Are assigned to the user class
Are not disabled (the specified userAccountControl setting does not equal 2)

Note: The last filter (sAMAccountName=$logon) is a specialized filter required by the PolicyTech application, and $logon is a PolicyTech code variable.

Now, suppose you wanted to include all users who were members of the Researchers group, which belonged to the Users OU in the MyCompany.com domain. You would add the following to the end of the filter immediately inside the outermost right parenthesis:

(memberOf=CN=Researchers,OU=Users,DC=MyCompany,DC=com)

So, the complete filter string would look like the following:

(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(sAMAccountName=$logon)(memberOf=CN=Researchers,OU=Users,DC=MyCompany,DC=com))

To specify more than one group in the same filter, use the pipe symbol ( |, which is the OR operator) and enclose each memberOf filter in parentheses, as shown in the filter string below:

(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(sAMAccountName=$logon)(|(memberOf=CN=Researchers,OU=Users,DC=MyCompany,DC=com)(memberOf=CN=Delevelopers,OU=Users,DC=MyCompany,DC=com)))

Additional filter notes:

AD is said to be case aware but case insensitive. Case aware means that if you use mixed case in something like an object name, AD will store the name exactly as you typed it. And case insensitive means that AD interprets lowercase letters the same as their uppercase counterparts for search and filter strings. For example, AD interprets DC=MyCompany and dc=mycompany as the same value.
If you decide to filter by groups, we recommend setting Organization Unit (OU) to the domain root (such as DC=MyCompany,DC=com) rather than an OU within the domain and then exclusively using groups to filter users.
Nesting of groups is NOT supported. If an LDAP query includes a nested group, only those users in the top-most group will be filtered (included or excluded).
After making changes to an existing OU filter, be sure to test that OU's connection again in the Domain Information window.
If you decide to test an LDAP filter string by doing a custom search in Active Directory Users and Computers, you will need to either temporarily remove the (sAMAccountName=$logon) filter from the string or change the $logon value to * (to select all account names).
If, after syncing AD users, a user who did not match the filter criteria tries to log in to PolicyTech, that user will see a message stating that the user name and password are invalid.

Synchronization Mapping

In the Synchronization Mapping area of the Domain Information window, you can tell PolicyTech what information you want pulled from this domain's user profiles into PolicyTech user profiles. PolicyTech will import the user profiles initially and then keep the user properties you specify in sync with their corresponding AD properties.

Important:

The sync is a one-way, read-only process. PolicyTech never changes user properties in AD.
We recommend that you re-read the How the Sync Works section above before deciding which properties to map.
If you've manually created a user in PolicyTech prior to the initial AD sync, the only way to avoid creating a duplicate user when you perform the initial sync would be to add and enable that user's domain in PolicyTech and then assign the user to that domain in PolicyTech User Manager. If, and only if, the user's AD logon name matches that user's PolicyTech user name, then performing the initial sync will update that user's existing user profile in PolicyTech instead of creating a new (duplicate) user.
If you've added custom attributes, (see Custom Attributes), those will also appear in the Synchronization Mapping list.

In the Synchronization Mapping area of the Domain Information window, PolicyTech user properties are listed in the Enabled column and AD user properties in the AD Property column.

To enable the syncing of a user property, select it.

Check the default AD property to make sure that is the property source you want. If not, type a different AD property using its LDAP attribute name.

Remote Domain

If your PolicyTech system is hosted by NAVEX Global or your Active Directory service is on a different network than the PolicyTech server, you will need to provide a URL to a web page that can pass the information between PolicyTech and Active Directory. For hosted systems, this URL is filled in by an implementation specialist during installation.

If necessary, type a URL in the Remote Domain area.

(Optional) Set Up and Activate Automated Synchronization

If you want the PolicyTech user database to automatically be synced with Active Directory users, see Automated User Synchronization.

(Optional) Set Up Integrated Authentication

Important: The Integrated Authentication Module settings apply only if PolicyTech is installed on your organization's premises. If PolicyTech is hosted by NAVEX Global, contact Customer Support at 888-359-8123 (toll-free in the U.S. and Canada) or 208-359-8123 for help in setting up Single Sign-On or using SAML for user authentication.

You can have Active Directory users automatically authenticated for using PolicyTech as soon as they log on to the network. This means that they can open PolicyTech without being required to enter a user name or password. This capability is built into and installed with PolicyTech—you need only provide the correct URLs to activate it.

URL to Program. Type the URL, including the including the scheme (http:// or https://), used to access your installation of the PolicyTech program. The program URL is typically in the format http://[company name].policytech.com.

Authentication URL. Type the same URL you typed for URL to Program and append /ADAuth/, as in the following example: http://mycompany.policytech.com/ADAuth/

Note: If AD users click LOG OUT in PolicyTech or if their PolicyTech session times out, they will be presented with the login screen. At that point, they can either simply refresh the web page or type their AD credentials, select the correct domain, and then press Enter.

Save Active Directory Settings

When you're finished setting up AD sync, and whenever you make changes to the settings in the future, be sure to click Save.