Knowledge Base

LDAP Settings

Last Modified:
22 Jan 2019
User Level:
Administrator

Description

TERMINALFOUR can integrate with your directory service (e.g.: Microsoft Active Directory) using LDAP(S).

LDAP settings permit the user login request to be authenticated against the directory service rather than against TERMINALFOUR's internal user database. This streamlines the user provisioning and authentication processes for your users and you.

While you can choose to use either directory based authentication or TERMINALFOUR authentication, you can also use a combination of both.

After configuring a connection to the directory service, each user record matching set criteria are imported into TERMINALFOUR's user list. For a minimum setup, you'll need the following user information from your directory service:

  • first name attribute
  • last name attribute
  • username / user ID attribute
  • email address attribute

User passwords are never imported; authentication always takes place against the directory server.

Before you start

There are important things to know before you can use LDAP authentication with TERMINALFOUR:

  • TERMINALFOUR can integrate with a single directory service only
  • TERMINALFOUR does not support Continuation References in your directory structure
  • When configuring the link between TERMINALFOUR and your directory service ensure you have an LDAP or Active Directory administrator present to assist as they'll be the most familiar with the structure of your directory tree.
  • TERMINALFOUR can only deal with user records when reading your directory. For this reason, it must be set to look at your user containers (OUs) rather than the groups you may have defined
  • Treat all attributes and values as being case sensitive whether your underlying directory service is case sensitive or not
  • Many LDAP browsers (such as Microsoft Active Directory Browser) allow renaming of names and values into a more human-readable format, however, TERMINALFOUR reads the actual names and values for attributes on a user record
    • TERMINALFOUR suggests you use the Java-based browser JXplorer to verify the names and values in your directory. TERMINALFOUR expects to find exactly what is specified in JXplorer.
  • When connecting using LDAPS you must import the SSL certificate for your directory server into a Java Keystore and have your application server (Tomcat, etc.) read this keystore when starting.
  • As of version 8.2.3, you must import the SSL certificate into the TERMINALFOUR keystore as per the documentation on Keystore Configuration

You must always maintain one non-directory account (local user) for use with TERMINALFOUR administration should there ever be a problem connecting to your directory service. This account is also required when upgrading TERMINALFOUR.

LDAP management

To manage your LDAP settings, go to System Administration > User Rights & Roles > LDAP Settings. The starting page is shown below:

LDAP Settings start page screenshot 

From this point, you can manage your LDAP settings. In the center of the page is a table displaying Configured contexts. From the Actions button, you can either edit or delete an entry. From this page, there are options to:

Create new context

Consider an LDAP context in TERMINALFOUR to be a collection of rules which are used when searching for users to import.

Each context should refer to an Organizational Unit (OU) in your directory which contains users records. As an example: ou=Development, ou=Staff, dc=terminalfour, dc=com

In addition to specifying the target for the context, you can also specify some filters which are used to exclude or include users based on particular attributes and values.

When you click Create New Context, this screen opens:‌

Configure the following options:

ItemDescription
Name This is the name you assign to this import configuration. Example values include "Marketing Team", "IT Dept", "Full Time Staff", and others associated with the organization.
Context

Specify the LDAP context associated with the group of users for import. This is the full DN of the OU containing user records. This is a case-sensitive value (regardless of whether your directory service is case sensitive or not.) Examples: ou=Staff, c=terminalfour, dc=com

Do not use a group definition as the target for the context. TERMINALFOUR only reads user records, it does not read a group to determine the users who are members of it.

Authlevel Sets the user level assigned to users created during an import of this context. For further information on the user types, refer to the documentation on User rights & roles.
Default authentication method Sets the default authentication method for new users imported by this LDAP context.
Choose group Sets the group that users are assigned to when created during an import of this context.
Include children Sets whether or not sub-containers are included during an import.

Context filters

You can add multiple filters (both Simple and Advanced) to each context. If there are multiple filters, by default a user record must fulfill all filters to be imported into the context, but an OR logic can be created with Advanced filters.

Simple filters

Simple filters can be used to target certain users in a given OU. They represent a pairing of attributes and values. Both the attribute and the value specified here is case sensitive (regardless of your directories case sensitivity). These filters are mostly used to import users of certain groups from the directory.

ItemDescription
Filter

Choose an attribute from your directory which specifies group membership is memberOf. For example, the group DN for library staff is: ou=Library,ou=Staff,ou=Groups,dc=terminalfour,dc=com

When targeting groups you must enter exactly what appears on the user record to indicate the group membership.

Value Enter the intended attribute value.
Exclude Check this box to exclude users matching this filter instead of including just users who match it.‌

Advanced filters

Advanced filters are similar to Simple filters but allow you to write LDAP queries to match multiple names or values and does not restrict the filter to using attribute values. To create an Advanced Filter, Enter the Filter query and click Add filter.

Processing Simple and Advanced Filters

When processing simple and advanced filters within a context, by default, AND logic is used. Advanced filters need to be used to use OR logic. To use OR operators, a '|' symbol is used.

The example below outlines an advanced filter that will import multiple users based on their sAMAccountName. The '|' is added to the beginning of the filter and then each attribute/value pair that you want to use within the filter is encapsulated individually.

(|(sAMAccountName=CiaraF)(sAMAccountName=VincentO)(sAMAccountName=KevinW))

For each filter that is added, it will also process this with AND logic. If you have a simple filter and then an advanced filter that uses OR logic, the LDAP context will query the active directory for users/objects that match the values in both queries.

You can learn more about LDAP filters here.

Once complete, click Save changes to save the context.

Import users

To import users, you need to be on the LDAP settings page. Click the Import users button. The popup window, shown below, appears. If you want to continue, click the Confirm button.‌

If the import is successful this popup window appears:‌

Schedule imports

To schedule an import, you need to be on the LDAP settings page. Click the Schedule import button. A popup window appears, shown below. 

ItemDescription
Next due Set the date and time for the next (or first) execution of this task.
Execution interval The execution interval of the task e.g. 1 hour, 1 day, 10 minutes, Once
Fixed rate Sets if the task to add/update should run on a fixed rate.
Infinite Check here to continue imports indefinitely. If you do not check this box, then set a number of repetitions in the field below.
Maximum executions Set the maximum number of times this task should run. 

When your entries are complete, click Confirm. This adds the import to the Task Scheduler.