LDAP Settings
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 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. |
---|---|
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.
|
Step 3 | Click the Update 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: ldaps:// ), you will have to configure the Universal Controller truststore with an X.509 CA certificate in either of these formats:
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, |
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. |
Search | This section contains search information. |
Base DN | Starting point for searching the directory. For example: |
User Id Attribute | LDAP attribute for the specified User ID.
|
User Filter | Search filter for users. |
User Target OU List | Single- or multi-level target OU's (Organizational Units) within the Base DN directory to filter for user records. |
Group Filter | Search filter for groups. |
Group Target OU List | Single- or multi-level target OU's within the Base DN directory to filter for group records. |
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 |
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 |
Login Method | Login method(s) that an LDAP-provisioned user can authenticate with by default. The default is applied only at user creation time.
|
Buttons | This section identifies the buttons displayed above and below the LDAP Settings that let you perform various actions. |
Update | Unable to render {include} The included page could not be found. |
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:
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: |
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 ( |
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.