Title: Configuring Active Directory

Configuring Traction to use Microsoft Active Directory



This section explains how to configure Traction to work with Active Directory.

Open the Active Directory Editor



Note: If you have configured Traction to use Active Directory, you can continue to use your existing configuration (it will appear in the list of available User Directories), but you can not edit the settings using the web interface. To edit using the Active Directory configuration editor, you will need to use the editor to create a new profile for your Active Directory server.

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 > Current Journal.



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.



Select "Microsoft Active Directory Server" from the list. This brings up the Active Directory editor.



Overview



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 pull-down 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 Active Directory 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

Behavior

No

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

Yes

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


Active Directory Server Settings



Enter the correct values for these settings from your Active Directory

Domain Controller





Default Domain



The default domain setting lets you choose against which domains Traction will authenticate users. You can specify one or more domains (comma-separated) in this control.



When Traction prompts for a username and password, e.g. when using Active Directory but not NTLM, it will check each of the domains in this list for a matching username. If your organization uses a Global Catalog server and partitions users into multiple domains, you should enter the list of all domains from which a user might need to log in.

Note: For Traction's multi-domain support to work correctly, usernames must be globally unique; if the user JSMITH is defined in domain A, JSMITH should not be a different user in domain B.

LDAP Search Base



Enter the path of the sub-tree in LDAP where you would like to search for users.

Important! The domain name corresponding to this path must be resolvable by name (either via DNS or a hosts file) from the machine on which the Traction server is installed.

For example, if you specify the following Search Base:



You must be able to get a response by running a ping command, like this:



If your ping fails, you can add an entry to the hosts file (either /etc/hosts on Unix or the file listed below on Windows), like the following:



LDAP Port



Enter the port your Active Directory uses for LDAP connections. The default is 389, which appears in the template.



Authentication



This refers to how the Traction server authenticates its connection with your LDAP server. Traction connects to LDAP in order to do User, Group, and Property (e.g. fullname, email address) lookups.

There are two options: None and Simple.



If None is selected, Traction will attempt to make an anonymous connection to the Active Directory server. If your server allows anonymous connections to perform the necessary lookups, this may suffice for you. Most Active Directory 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 domain-qualified, as shown in the example. Just the name of an account does not suffice, even if you have specified a default domain.

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 Active Directory will not be able to log in to Traction. 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



Login Method



Most customers using Active Directory use NTLM, which logs in users automatically, creating a Traction account with the same UserID as their Windows login the first time they visit Traction. Using NTLM, users never need to enter their Traction username or password, and Traction is never made aware of the user's password; instead it gets a hash from the login manager that it verifies with Active Directory.



Important Security Note: Realms and Cookies require users to enter their passwords when they visit Traction, and differ in how the login is maintained. Cookies allows the login to be maintained using either persistent or session cookies stored in the web browser, depending on whether the administrator enables -- and the user selects -- a "Remember me" checkbox on the login form. When the user logs in using realms, the password is sent uuencoded, which is considered cleartext for security purposes. Using cookies, the password is encrypted and base-64 encoded. For this reason, if you elect to use realms or cookies, we urge you to use HTTPS rather than HTTP. HTTPS is easy to configure in Traction; see the instructions in this help document. Once the password has been received by Traction and authenticated by Active Directory, when using cookies, the login session is maintained using an encrypted cookie. If realms is used, the original login information is passed back and forth with each request. Since NTLM never reveals the user's password to Traction, we consider NTLM to be more secure than cookies or realms.

NTLM Options



If NTLM is enabled, you can choose whether or not to allow Basic (realms) authentication for browsers or other clients that do not support NTLM, such as RSS readers.



If you elect to Enable Basic Authentication, it will only be supported on HTTPS connections, unless you also enable the next option:



Note that the option to enable Insecure Basic Authentication is only available if you have already selected that you want to enable basic authentication.



Enable Traction User Management



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



Note: This option is only available when you select Cookies or Realms; it is not supported in conjunction with NTLM.

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.



Additional Options



In rare cases, Traction support may suggest that you add text in this field to access very unusual configuration settings.



Principal Cache Settings



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

Group Membership Search





For Active Directory, this setting should be set to Direct.

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 Active Directory 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



When you have finished entering all the 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.

Important! Note: The username will be tested against all the domains listed in the Default Domain property. If you want to test a user in a different domain than those listed, or in a specific domain, you can enter the user's domain-qualified username, e.g. THEDOMAIN\username.



If the username and password are verified by Active Directory, Traction will report Login Successful.



If the password is not correct, Traction will report:



If the username can not be found, Traction will report:



If the login test does not succeed, go back and check your settings and make sure that you can ping the Active Directory server by its DNS name from the computer running Traction.

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.



Inspecting Account Details



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:



Note: Traction uses the user's Active Directory GUID to maintain the mapping between the Traction user and the Windows user.

Troubleshooting



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.



Attachments:
image267.jpg
image268.jpg
image269.jpg
image270.jpg
image801.jpg
image349.gif
image272.jpg
image273.jpg
image274.jpg
image350.gif
image351.gif
image352.gif
image275.jpg
image358.gif
image359.gif
image360.gif
image370.gif
image371.gif
image361.gif
image362.gif
image363.gif
image276.jpg
image365.gif
image366.gif
image367.gif
image368.gif
image277.jpg
image369.gif
image849.gif
image850.gif
image851.gif
image852.gif
image278.jpg
image279.jpg
image372.gif
image373.gif
image280.jpg
image293.jpg
image374.gif
image375.gif
image281.jpg
image282.jpg
image394.gif
image300.jpg
image283.jpg
image284.jpg
Related Articles
parents (1)
Doc35: Choosing and Configuring a User Directory
referenced by (6)
Doc1444: Creating New UsersDoc351: Installation and Configuration GuideDoc312: Using Access Control Lists (via Configuring NTLM and Active Directory)Doc305: Troubleshooting Using the Log File ViewerDoc43: Configuring NTLM and Active DirectoryDoc35: Choosing and Configuring a User Directory
Article: Doc40 (permalink)
Date: March 22, 2008; 3:49:32 PM Eastern Daylight Time

Author Name: Documentation Importer
Author ID: importer