Configuring 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 initial user import, user list maintenance (daily synchronization), and 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.

Considerations

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

  • How much AD user information do you want pulled into PolicyTech user records?
  • If AD does not 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?

    Important: If you already have users defined in PolicyTech, contact NAVEX Customer Support by submitting a request in the Community before starting a sync setup to avoid many issues that could result from syncing existing PolicyTech users with AD users.

  • If a user is deactivated or deleted in AD, do you also want that user deactivated or deleted in PolicyTech?
  • If you do not 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 are 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?

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.

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

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

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.

Step 4: 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 does not 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.

Step 5: 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 do not 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: 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, a new, duplicate object will be created in PolicyTech when AD is synced.

Enter Domain and Organizational Unit Information

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 Connection Settings and Synchronization Mapping.

  1. Click Settings & Tools > IT Settings, and then click Login Settings.
  2. Click the Active Directory tab, and then click Add Domain.
  3. 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.

  4. For Authorized User, you need to provide PolicyTech with the credentials of a user within the specified domain. 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 is an best practice. 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 will 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.

  5. Type the user name and password of the authorized user with AD permissions.
  6. (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).
  7. 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.

  8. Select the PolicyTech site where you want AD users added and synced.
  9. Click Add Organizational Unit (OU). You must 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.

  10. Type the OU's LDAP distinguished name that uniquely identifies it within AD.

    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

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

    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, consider 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.
  12. 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.

  13. Click Save.
  14. 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.

  15. (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. Specifying the domain root as the only OU and then using a filter string to include or exclude specific user groups is a best practice for optimal performance.
    • If you add multiple OUs, they must all be from the same domain.
  16. Continue with the steps in the Synchronization Mapping section below.

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

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

  2. 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.
  3. If your PolicyTech system is hosted by NAVEX 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.