Overview

Note

The information provided on this page assumes you have a working knowledge of LDAP authentication.

LDAP Settings, which allow you to enable the LDAP bridge for both UNIX and Windows operating systems, are available through the user interface.

You can set up Universal Controller to use LDAP authentication for:

Credentials for running tasks
User logins

Credentials for Running Tasks Authentication

To use LDAP authentication for Universal Controller user credentials:

UNIX

If you want the credentials for Universal Agent to go through LDAP authentication, the UNIX machine on which the Agents reside require PAM. The Agents must be configured to use PAM, and PAM must be configured to use LDAP.

The UNIX systems that support PAM authentication are AIX, HP-UX, Linux, and Solaris. Refer to Security of Universal Agent Components to see which Agent Server components can use PAM authentication on these systems.

Set up your PAM configuration to use the PAM LDAP module. Depending on your LDAP version, some other configuration steps may be required. Once PAM is configured, tasks specifying credentials will authenticate over LDAP transparently.

Windows

While no set-up steps are required to specifically enable Domain/Active Directory credential authentication, the target system does need to belong to a Domain or Active Directory Forest. When you specify credentials for a task, use DOMAIN\user as the user name.

User Login Authentication

Step 1

From the Administration navigation pane, select Configuration > LDAP Settings. The LDAP Settings page displays.

Step 2

Enter / select your LDAP Settings, using the field descriptions below as a guide.

Required fields display an asterisk ( * ) after the field name.
Default values for fields, if available, display automatically.

Step 3

Click the button.

For information on how to access additional details - such as Metadata and complete database Details - for LDAP Settings (or any type of record), see Records.

Note

In order to log in to the Controller using LDAP, you must set the LDAP Synchronization Enabled Universal Controller System property (Administration > Configuration > Properties in the Controller user interface) to true.

LDAP Settings Field Descriptions

The following table describes the fields and buttons that display in the LDAP Settings.

Field Name	Description
Connection	This section contains information on the LDAP connection.
URL	URL of the LDAP connection. For example: `ldap://ldap.stonebranch.com:389/` `ldaps://192.202.185.90:636/` To use SSL/TLS encryption (`ldaps://`), you will have to configure the Universal Controller truststore with an X.509 CA certificate in either of these formats: DER-encoded binary Base64-encoded You can also specify a space-separated list of URLs. Universal Controller will attempt to use each URL in turn until a successful connection is created. For example, `ldap://ldap1.stonebranch.com:389/ ldap://ldap2.stonebranch.com:389/`
Bind DN or User	Distinguished Name (DN) or User ID used for initial access to the LDAP server.
Bind Password	Password associated with the Bind ND or User.
Use for Authentication	If enabled, indicates that LDAP will be used for password authentication.
Allow Local Login	If the LDAP Synchronization Enabled Universal Controller system property is false, or if it is true but the Use for Authentication field is not enabled, an administrator must explicitly specify Allow Local Login to allow local account login for users that were provisioned through LDAP synchronization. This option is intended only to provide temporary access while an LDAP directory is unavailable. An administrator will need to update the local account password for any LDAP-synchronized user who requires temporary local account login, as the provisioned password would be unknown.
Search	This section contains search information.
Base DN	Starting point for searching the directory. For example: `dc=stonebranch,dc=com`. If you do not specify a Base DN, the search starts as the root of the directory tree.
User Id Attribute	LDAP attribute for the specified User ID. Options: sAMAccountName cn uid Other...
User Filter	Search filter for users. If you do not specify a User Filter, the server uses `(&(objectClass=user)(objectCategory=person))`.
User Target OU List	Single- or multi-level target OU's (Organizational Units) within the Base DN directory to filter for user records. For example, `OU=Employees` or `OU=Employees,OU=Users`. If you do not specify one or more OU's, the entire sub-tree from the Base DN will be searched.
Group Filter	Search filter for groups. If you do not specify a Group Filter, the server uses `(&(objectClass=group)(objectCategory=group))`.
Group Target OU List	Single- or multi-level target OU's within the Base DN directory to filter for group records. For example, `OU=Universal Controller` or `OU=Universal Controller,OU=Groups`. If you do not specify one or more OU's, the entire sub-tree from the Base DN will be searched.
Advanced	This section contains advanced information.
Connection Timeout (Seconds)	Timeout for connecting to the LDAP server.
Read Timeout (Seconds)	Timeout for reading from the LDAP server.
User Membership Attribute	LDAP attribute for the groups in which a user is a member. If you do not specify a User Membership Attribute, the LDAP server uses memberOf (see the `uc.ldap.users.synchronize_indirect` Universal Controller start-up property.
Group Member Attribute	LDAP attribute for the members of a group. If you do not specify a Group Member Attribute, the LDAP server uses member (see the `uc.ldap.groups.update_members` Universal Controller start-up property.
Login Method	Login method(s) that an LDAP-provisioned user can authenticate with by default. The default is applied only at user creation time. You can use the Ctrl key to select multiple methods. Only one of Standard or Standard / Authenticator App (TOTP) can be selected, not both. Options: Standard Single Sign-On Standard / Authenticator App (TOTP)
Buttons	This section identifies the buttons displayed above and below the LDAP Settings that let you perform various actions.
Update	Saves updates to the record.
Test Connection	After saving the LDAP Settings to the database, click Test Connection to run a connection test.
Refresh	Refreshes any dynamic data displayed in the LDAP Settings.
Tabs	This section identifies the tabs across the top of the LDAP Settings page that provide access to additional information about the LDAP Settings.
Mappings	List of User and Group columns mapped to LDAP attributes that enables you to customize how the User/Group records get populated from LDAP.

Mappings Tab

The Mappings tab of the LDAP Settings page displays a list of Controller columns mapped to LDAP attributes.

Mappings Tab Column Descriptions

The following table describes the default columns displayed on the Mappings tab:

Type	Type of records.
Column	Controller column being mapped to LDAP attribute.
Attribute	LDAP attribute to which the Controller column is being mapped.
Updated By	User who last updated this record.
Updated	Date and time this record was last updated.

Mapping Details

To view the Mapping Details for a mapping on the list, click the Details icon next to that mapping.

For example:

Best Practices

The following best practices are provided to assist you in configuring LDAP.

Determining your User OUs and Group OUs

1. Determine which users/groups need to have access to Universal Controller.
2. Determine which Organizational Units (OUs) those users/groups belong to.
3. Build your list of user and group OUs.

Consider the following organizational units for required Users and Groups.

Users

OU=NorthAmerica,OU=CorporateUsers,OU=Corporate,DC=stonebranch,DC=com

OU=Students,OU=Corporate,DC=stonebranch,DC=com

Groups

OU=AtlantaGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com

OU=OntarioGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com

OU=OtherGroups,OU=Corporate,DC=stonebranch,DC=com

You specify the User and Group Target OUs relative from the Base DN. In this case, the Base DN would be OU=Corporate,DC=stonebranch,DC=com.

For the User Target OU List LDAP Settings field, you would have the following entries:

OU=NorthAmerica,OU=CorporateUsers

OU=Students

For the Group Target OU List LDAP Settings field, you would have the following entries:

OU=AtlantaGroup,OU=CorporateGroups

OU=OntarioGroup,OU=CorporateGroups

OU=OtherGroups

Customizing Users and Groups Lists to see DN of LDAP Synchronized Users and Groups

For each User and Group object in the LDAP directory that matches the configured search and OU configuration in Universal Controller, a User and Group record are created in the Controller to represent those objects.

For each User and Group record in the Controller that represents a synchronized LDAP User or Group, the Source column on the Users list or Groups List, respectively, contains the Distinguished Name of that User or Group in LDAP. (For Users and Groups created locally in the Controller, the Source column is blank.)

For example:

Source Column for a User	ldap:CN=Stonebranch User,OU=TestUsers,DC=qad,DC=stone,DC=branch
Source Column for a Group	ldap:CN=UnvControllerParent,OU=TestGroups,DC=qad,DC=stone,DC=branch

Note

By default, the Source column is not shown on either lists. For instructions on how to add the Source column, see Selecting Columns / Column Locations for a List.

LDAP Server Operations

If LDAP is configured for Universal Controller, it refreshes every 24 hours.

Additionally, the Controller provides two Server Operations that let you force an LDAP refresh:

LDAP Refresh (Asynchronous)
This server operation performs an LDAP refresh in the background and sends entries to the Universal Controller log.
LDAP Refresh
This server operation perform an LDAP refresh that writes all log entries to the user interface as well as to the log, and prevents all other user activity while the process is running. If you estimate the refresh could take a considerable amount of time, we recommend you use the LDAP Refresh (Asynchronous) server operation.

LDAP Settings Fields

The following Best Practices should be followed for specific fields in the LDAP Settings.

URL

To avoid an inadvertent synchronization of LDAP using an incomplete LDAP configuration, refrain from providing a value for this setting until LDAP configuration has been completed.

Once LDAP configuration has been completed, you can utilize the LDAP Refresh server operation to verify your configuration.

Base DN

All directory searches are relative from the base object defined by the specified DN. The Base DN (or search entry point) should be the lowest base object in the directory for which both the User and Group OUs can be searched from.

If your Users are in:	OU=CorporateUsers,OU=Corporate,DC=stonebranch,DC=com
And your Groups are in:	OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com
Your Base DN can be:	OU=Corporate,DC=stonebranch,DC=com

User Filter

This setting defines which objects the Controller considers as Users when it queries objects in the configured User OUs (see pointers on configuring User OUs).

By default, the server will use filter (&(objectClass=user)(objectCategory=person)).

For Active Directory (AD)

At a minimum, specify the following:

(&(objectClass=user)(objectCategory=person))

This filter would match both user and inetOrgPerson objectClasses. objectCategory=person is added for two reasons:

It is an indexed attribute, so the query performance is optimized.
Without it, Computer objects could be synchronized.

For example, in AD, a computer objectClass extends from a user objectClass, but a computer's objectCategory=computer, not person.

Note

Once an object (User or Group) is synchronized into the Controller, it will not be deleted if search filter/OU criteria are narrowed. However, broadening your search filter/OU scope will pull in new objects. After modifying your LDAP configuration to narrow the search scope, a Controller administrator will need to delete any Users and Groups that are no longer desired/match the LDAP configuration.

You can synchronize Users that belong only to a specific Group, such as one created for Unversal Controller.

For example:

CN=UnvControllerGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com

To ensure that only Users belonging to UnvControllerGroup are synchronized, modify the recommended minimum user search filter:

(&(objectClass=user)(objectCategory=person)(memberOf=CN=UnvControllerGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com))

You can synchronize Users that belong any Group that is a descendant of UnvControllerGroup.

For example:

UnvControllerGroupA is a member of UnvControllerGroup.
UnvControllerGroupB is a member of UnvControllerGroupA.
UnvControllerGroupC is a member of UnvControllerGroupB.

To achieve this in AD, modify the search filter used to synchronize users that belong only to a specific Group:

(&(objectClass=user)(objectCategory=person)(memberOf:1.2.840.113556.1.4.1941:=CN=UnvControllerGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com)))

Essentially, replacing memberOf with memberOf:1.2.840.113556.1.4.1941: will ensure that nested groups are considered.

1.2.840.113556.1.4.1941 (Matching rule OID) is a special "extended match operator" that walks the chain of ancestry in objects all the way to the root until it finds a match (see http://msdn.microsoft.com/en-us/library/windows/desktop/aa746475(v=vs.85).aspx).

Group Filter

This setting defines which objects the Controller considers as Groups when it queries objects in the configured Group OUs (see pointers on configuring Group OUs).

By default, the server will use filter (&(objectClass=group)(objectCategory=group)).

For Active Directory (AD)

It is recommended that you optimize the query performance by incorporating the indexed objectCategory attribute:

(&(objectClass=group)(objectCategory=group))

To limit the Groups synchronized from LDAP to a few specific Groups or Groups by name, adjust the Group search filter to include a query on the CN (common name) attribute.

For example, to synchronize a single group named CN=UnvControllerGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com, modify the recommended minimum group search filter:

(&(objectClass=group)(objectCategory=group)(cn=UnvControllerGroup))

To synchronize only UnvControllerGroupA, UnvControllerGroupB, and UnvControllerGroupC, use the following filter:

(&(objectClass=group)(objectCategory=group)(|(cn=UnvControllerGroupA)(cn=UnvControllerGroupB)(cn=UnvControllerGroupC)))

To synchronize any Group that is a (direct) member of UnvControllerGroup, use the following search filter:

(&(objectClass=group)(objectCategory=group)(|(cn=UnvControllerGroup)(memberOf=CN=UnvControllerGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com)))

To synchronize any Group that is a descendant of UnvControllerGroup (multi-nested groups), use the following search filter:

(&(objectClass=group)(objectCategory=group)(|(cn=UnvControllerGroup)(memberOf:1.2.840.113556.1.4.1941:=CN=UnvControllerGroup,OU=CorporateGroups,OU=Corporate,DC=stonebranch,DC=com)))

Essentially, replacing memberOf with memberOf:1.2.840.113556.1.4.1941: will ensure that nested groups are considered.

1.2.840.113556.1.4.1941 (matching rule OID) is a special "extended match operator" that walks the chain of ancestry in objects all the way to the root until it finds a match (see http://msdn.microsoft.com/en-us/library/windows/desktop/aa746475(v=vs.85).aspx).

If you do not want to synchronize Groups:

1	Do not explicitly specify a value for the Group search filter.
2	Do not specify any target Group OUs (organizational units).
3	Ensure that the Universal Controller Start-up Properties file (`uc.properties`) contains the following property configuration: uc.ldap.groups.filter_indirect=true (If uc.ldap.groups.filter_indirect=true, any Groups synchronized indirectly - that is, through a User's memberOf attribute - will honor the Group Filter and Group Target OU List.)

Note

The uc.ldap.groups.single_parent_per_child start-up property should be set to true only if your Groups being synchronized from AD have at most one parent Group. When synchronizing Groups, the default Controller behavior is to copy the members of a Sub Group into the Parent Group. If this property is set to true, the Controller assumes that each Group has, at most, a single Parent Group and will use the Parent field on the Group definition to maintain the hierarchy instead of copying members.

SSL/TLS Secured LDAP (LDAPS)

Universal Controller supports the use of LDAPS instead of the non-encrypted LDAP connection offered in the Controller.

It requires setting up a truststore (keystore) and setting the following properties in the Universal Controller Start-up Properties (uc.properties) file:

You must make sure that the LDAP server's certificate exists in the truststore that is referenced by these two properties.

When these configurations have been made, use ldaps:// for the URL prefix in the LDAP Settings Field Descriptions.