Configuring Active Directory Settings

If your organization uses Microsoft Active Directory to manage network user accounts, you can configure Policy & Procedure Management 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 Policy & Procedure Management user list are to define and maintain users manually or to export a user list from another database and import that list into Policy & Procedure Management.

Considerations

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

  • How much AD user information do you want pulled into Policy & Procedure Management user records?
  • If AD does not include all of the user data needed for Policy & Procedure Management 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 Policy & Procedure Management, 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 Policy & Procedure Management users with AD users.

  • If a user is deactivated or deleted in AD, do you also want that user deactivated or deleted in Policy & Procedure Management?
  • If you do not want all of the users in an AD domain synced with Policy & Procedure Management, 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 Policy & Procedure Management 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 Policy & Procedure Management sync process to access AD? Will you use a service account or a normal user?
  • Will your Policy & Procedure Management site be required to use SSL to authenticate to AD and, if so, is SSL set up correctly on the server hosting Policy & Procedure Management?

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 Policy & Procedure Management pulls from each AD domain you specify.

Step 1: Attempt to match the AD GUID. Policy & Procedure Management users that are synced with AD users include an extra field of data in their Policy & Procedure Management 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, Policy & Procedure Management first checks to see if the AD user's GUID has already been added to a Policy & Procedure Management 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 Policy & Procedure Management user profile can only be done by the AD sync feature. The GUID property is not available in the application 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 Policy & Procedure Management 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 Policy & Procedure Management user.

If the sync finds no matching GUID or user name, it creates a new Policy & Procedure Management 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 Policy & Procedure Management user, these properties are used regardless of whether or not they are enabled and mapped in the domain information you will later add in Policy & Procedure Management Login Settings.

Policy & Procedure Management 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 Policy & Procedure Management Login Settings†

Department

Mapped property in Policy & Procedure Management Login Settings†

Domain

Domain specified in Policy & Procedure Management Login Settings in the Organization Unit (OU) definition that included this user in the sync

*When AD sync is enabled, Policy & Procedure Management ignores whatever is stored in the Password field of the Policy & Procedure Management 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 Policy & Procedure Management, you will be required to specify a default site for adding new users and will have the opportunity to map AD user properties to Policy & Procedure Management 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 Policy & Procedure Management job title, department, or site property is mapped for the sync, Policy & Procedure Management will compare the property value in the AD user profile to the existing Policy & Procedure Management job titles, departments, or sites.

  • If the job title, department, or site already exists in the application, the process moves on immediately to step 5.
  • If the job title, department, or site does not exist in the application, then Policy & Procedure Management 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 Policy & Procedure Management user properties that you chose to include in the sync. If any properties do not match, Policy & Procedure Management overwrites the information in the application 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 Policy & Procedure Management/AD sync feature will create new users, job titles, departments, and sites if they don't already exist in the application. If you add or modify any of these objects manually in Policy & Procedure Management, 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 Policy & Procedure Management object name varies even by a single character, a new, duplicate object will be created in Policy & Procedure Management when AD is synced.

Enter Domain and Organizational Unit Information

Policy & Procedure Management 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 Policy & Procedure Management.

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

  4. For Authorized User, you need to provide the application 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 Policy & Procedure Management 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 Policy & Procedure Management 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 Policy & Procedure Management.

  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 Policy & Procedure Management 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 Policy & Procedure Management 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 Policy & Procedure Management 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 Policy & Procedure Management 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. Policy & Procedure Management 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 Policy & Procedure Management application, and $logon is a Policy & Procedure Management 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 the application, 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 Policy & Procedure Management what information you want pulled from this domain's user profiles into Policy & Procedure Management user profiles. The application 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. Policy & Procedure Management never changes user properties in AD.
  • If you've manually created a user in the application 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 Policy & Procedure Management and then assign the user to that domain in Policy & Procedure Management User Manager. If, and only if, the user's AD logon name matches that user's Policy & Procedure Management user name, then performing the initial sync will update that user's existing user profile in Policy & Procedure Management 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, Policy & Procedure Management 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 Policy & Procedure Management system is hosted by NAVEX or your Active Directory service is on a different network than the Policy & Procedure Management server, you will need to provide a URL to a web page that can pass the information between Policy & Procedure Management and Active Directory. For hosted systems, this URL is filled in by an implementation specialist during installation.