Title: Configuring LDAP

Configuring Traction to use LDAP

This section explains how to configure Traction to work with LDAP servers like Novell eDirectory.

Open the LDAP

For New Journals

If you are creating a new Journal, click the New button underneath the User Directory selector on the Journal Setup interface.

For Existing Journals

If you want to change the user directory for an existing Traction server, click the Modify User Directory button on Server Setup | General.

This takes you to the Select User Directory page.

Click the New button. This will bring up the User Directory editor. The top-right lists any User Directory profiles that you have created, and also lists blank templates that you can use to create a new profile.


This file is a User Directory template, which you can fill in. Once you save the template, it becomes a profile that you can edit, delete, test, and use.

The file name of the template is listed under the template's type.

You can save your work as often as you like while you're doing this configuration. The save button is at the bottom of the page. You can name this configuration anything you like. As soon as you have made any changes, the Save button is enabled.

After you have saved, your profile appears in the pulldown menu at the top-right, and is selected:

The delete button is also enabled for profiles, allowing you to delete the current profile. If you click delete, you will be asked to confirm that you really want to delete the profile:

The file you are editing is displayed under the name you chose in the top-left:

The filename listed underneath is for informational purposes only, since the Traction interface uses the actual name you chose.

Enter a Description

This description is for your use in distinguishing between different profiles you may create.

General Settings

Allow Visitor Login

The default for LDAP installations is No, which means that no Visitor login is allowed at all, regardless of ACL settings.

Force Visitor Login

If you change Allow Visitor Login to Yes, you can then decide how Visitors login:

Force Visitor Login



When unauthenticated users first request a Traction page, they see content whose permissions make that content visible to Visitor.


When unauthenticated users first request a Traction page, they are taken to a login form that has a "Login as Visitor" button.

LDAP Server Settings

Enter the correct values for these settings from your Active Directory

Server URL

The LDAP Server URL contains most of the information that Traction requires to do LDAP lookups.

Traction supports normal LDAP and (secure ldap). By appending : and a port number, you can specify a different port to contact.

The middle of the URL is the tree in your LDAP server to search.

Important! If you want to use LDAPS, your LDAP server must be configured to work with LDAPS. Like HTTPS, LDAPS uses digital certificates to verify the identity of the server. Your LDAPS server will have a certificate installed in it, and when a client like Traction attempts to contact your server, the server will present its certificate to Traction. If your certificate has been signed by a top-level Certificate Authority (CA), Traction will make the connection. Otherwise, Traction will check its built-in store of trusted certificates to see if it recognizes your server. If it does, it will continue with the connection. If not, Traction will remember your server's certificate in its list of "untrusted certificates". You can use the Trust Manager to move the certificate to the list of "trusted certificates", or you can import your server's .pem or .cer file directly into Traction's list of trusted certificates. To get to the Trust Manager, you can click the "Click here to manage trusted certificates" link in the description above the LDAP URL. To learn more about the trust manager, see Overview of the Trust Manager.

The recommended sequence for setting up LDAPS is covered below.


This refers to how the Traction server authenticates its connection with your LDAP server.

There are two options: None and Simple.

If None is selected, Traction will attempt to make an anonymous connection to the LDAP server. If your server allows anonymous connections to perform the necessary lookups, this may suffice for you. Many LDAP servers require authentication. If your server requires authentication, select "Simple". When you select Simple, Account and Password fields open up underneath.

Important! The account you specify must be the distinguished name (DN), as shown in the example. Just a userid does not suffice.

Note: The password you enter will be stored using strong secret-key encryption in a Traction configuration file.

VERY IMPORTANT: If possible, the password you specify should be set not to expire. Otherwise, when the password expires, any users authenticated via LDAP will not be able to login. If you can not set the password not to expire, we recommend that you make a note of the password expiration date and change the Traction password followed by the system password before that date.

Advanced Settings

Enable Traction User Management

This option lets you define users in Traction that do not exist in your LDAP server, for example outside consultants or customers.

Change Password Message

You can override the default message that users will see if they arrive at a page in Traction that, with some user directories, would allow them to change their password.

Verify LDAP Password As

This setting lets you control whether the user's password is confirmed via a lookup by an administrator or an attempt to bind as the user with the supplied password.

LDAP Schema Mapping and LDAP Searches

LDAP schemas vary from company to company, but most LDAP schemas represent the information that is used by Traction. This section lets you specify the attributes used in your LDAP schema and the searches that Traction should use to do the lookups it performs.

By default the next two sections are shown collapsed on the setup page.

You can click the expand/collapse control to show and hide the sections.

LDAP Schema Mapping

When you click the expand button, you can edit the attributes used for each type of lookup.

The defaults listed are typical for an out-of-the-box NDS server. You can change the default that is listed, or click the checkbox to reset to the default when you press the save button.

Starting in version, Traction supports dynamic LDAP groups and indirect group membership searching. Dynamic groups are expressed in LDAP using a query instead of placing individual members in a group. Indirect search means checking the group for its members instead of checking a user for its groups (direct searching). Some LDAP servers require indirect searching for determining group membership.

LDAP Searches

Expanding the LDAP Searches control lets you modify the LDAP query that is used to look up information in your LDAP server. You will need to change the search specified if:

1. You change the schema mapping, as described above. In this case, you will need to edit the search expression to include the actual attribute your server uses.

2. You need to do a different lookup to return the indicated result set, e.g. you want email completion to match uid in addition to mail and fullname.

In the queries below {0} is substituted by the search term as indicated in each description..

Principal Cache Settings

Traction can optionally cache certain information in order to improve performance and reduce the load on your LDAP server.

Group Membership Search

If your LDAP server supports direct lookups, where the user object has a list of the groups it belongs to, we recommend that you choose direct. If the directory server can only return the members of a group, and can not return the list of groups of which a user is a member, you will need to select Indirect.

Enable Principal Cache

We generally recommend that you set this to yes. Caching reduces the time it takes to compute permissions, reduces load on your directory server, for systems with heavy usage it may reduce network bandwidth, and it generally improves performance.

If your LDAP server is especially large (generally speaking, hundreds of thousands of users or more), Traction may require significant memory resources to maintain the principal cache. If your server is exceptionally fast and you have plenty of CPU available, you may not notice appreciable benefit from the cache. In these scenarios, disabling the cache may be appropriate.

Cache Update Time

Often directory servers are synchronized with each other (e.g. a branch server synchronized with a remote server) at a specific time of day. Normally, you'll want Traction's cache to be updated after the synchronization completes. Enter the local time when you would like to make sure the cache is repopulated.

Cache Update Interval

This setting governs how frequently information in the cache should be re-fetched from the directory server. This is done automatically; the updated information replaces the existing information in the cache before it expires. That way, the information in the cache is always no older than the specified interval.

The time it takes to update the cache depends on the size of the directory. We have seen ranges from 20 seconds to 20 minutes. For larger directories, less frequent updates may be appropriate.

If a scenario arises where it's important to update the cache immediately, press the "Clear Caches" button in Server Setup to flush the cache and force the information to be re-requested from the directory server.

Testing Your Setup

Whenever you want to test your current settings, save your changes. After you click the Save button, the page will reload, and the Test button will become enabled.

Click the test button to launch the Test User Directory window.

Test Login

To verify that users can login using the profile you have created, enter a username and password and press the Test Login button.

If the username and password are verified by your LDAP server, Traction will report Login Successful.

If the password is not correct or the username can not be found in LDAP, Traction will report:

Test Lookup

Once you have the Login test working, you can lookup a user by typing any portion of the username or User ID:

Clicking lookup should return all matches in your Active Directory.

If you just click the Test Lookup button, Traction will warn you that you will return all hits.

If you select OK, all hits will be returned. Depending on how many entries you have in your server, this may take a long time and be slow to display.

You can also get details for any account by selecting the account and clicking the Show Details link:

This will pop up a window with the details for that user:


If you run into trouble and need more information to understand what might be going on, you can turn on debug logging and use the Log File Viewer to diagnose the problem. To learn more about this, see the section Troubleshooting Using the Log File Viewer.

Saving and Continuing

Once you are satisfied that both the Login and Lookup Tests are working, you can close the test window. You can also click the Close window button on the Configure User Directory page:

This should reveal the page you launched from, either Journal Setup or Modify user Directory, with your new profile selected:

You can now proceed with Creating a New Journal, or continue with the process of Changing User Directories.

Setting up LDAPS

Related Articles
Article: Doc41 (permalink)
Date: March 22, 2008; 3:50:16 PM Eastern Daylight Time

Author Name: Documentation Importer
Author ID: importer