Title: Changing User Directories and Migrating Principals

This chapter describes how you can change the User Directory used to manage users. For an overview of User Directories, see Choosing and Configuring a User Directory.

Background and Terminology

Each user known to Traction has a profile maintained by Traction. This profile is identified by the Traction User ID. User ID's are numbers assigned by the Traction server. The user's username is an attribute associated with the userid; usernames are used to log in.

Additionally, each user has a Principal. Permissions are assigned to Principals using Access Control Lists (ACL's).

The Principal for a user identifies the user in Traction's own built-in User Directory, or in LDAP or Active Directory. Principals for the different directory types look different. For example, Active Directory principals refer to the user's GUID, while LDAP Principals generally refer to the user's Common Name (CN). Principals for users managed by Traction refer to the Traction User ID.

Traction users with Administer Server permissions can change the Principal associated with users.

When a User's Principal changes, the system used to manage that user changes. Users with Active Directory Principals are Authenticated using Active Directory, and so on.

When changing Principals, Traction automatically updates all references to that Principal in existing ACL's, so that a user's permissions do not change when their Principal is switched to a different system.

Traction provides two interfaces for changing principals: a batch interface, and an interface for modifying individual users.

We refer to the process of switching from one Directory system to another migration; during this process, users are assigned new principals based on their identity in the other system.

Traction supports migrating principals from any known User Directory to any other known User Directory, e.g. from Traction to Active Directory, Active Directory to LDAP, LDAP to Traction, and so on.

Traction also supports hybrid User Directories, where different users may be authenticated by different Directories. The most common system is where some users (e.g. authenticated search engines, external contractors, clients, or customers) do not exist inside the corporate Directory and are managed via Traction, while most employees are managed using the Directory.

We will present an example of migrating to Active Directory, but the process is the same for migration to any User Directory.

Migrating from Built-In User Management to Active Directory

First, go to Server Setup | General.

Click the Modify User Directory button in the Current Journal section.

Select the User Directory to which you wish to migrate. If necessary, follow the instructions in the chapter Choosing and Configuring a User Directory to set up and test the target User Directory.

Make sure that the Migrate Principals checkbox is checked, then press Next.

The next page may take some time to load, while the Traction server attempts to contact the target User Directory and tries to automatically determine the new Principal for each user.

When Traction has completed this process, it will display a page that shows its best guess for the new Principal for each user. The users for whom Traction was able to find a match will be displayed in yellow.

You can now manually map any users who were not matched, or fix the mappings for any users that were guessed incorrectly, using the Lookup button. The lookup button uses the same lookup technique as in testing a User Directory. You can type part of the user's userid, fullname, or email address, and press Lookup:

This will pop up a dialog with a list of matching names. You can select the correct match, or enter another name to query inside the lookup. When you have identified the correct user, press OK.

The fields in the main page will be filled in with the result of the lookup.

If you wish to see the complete details, you can click the Show Details link.

This will pop a dialog showing detailed information for the selected user.

You can repeat this process as necessary to make sure that as many of the mappings as possible are correct. If you have a few you are uncertain about, you can modify them individually later in Personal Setup.

When you are ready, press the Finish button.

Traction will warn you that the system must be restarted.

When you press OK, you will see the restart message.

When the migration has completed and the server is back online, Traction will report:

You can press the home link to log in. You may be required to log in using your Active Directory credentials at this point. If you migrated all users, you should now be finished.

If you left any users unmigrated, you can follow the instructions below to modify individual accounts.

Modifying Principals in Personal Setup

Users with Administer Server permissions can change the Principal associated with a Traction user via the Modify Principal link on the Personal Setup | Permissions tab for that user.

This will pop up a Modify Principal dialog; you can use the Lookup control to search for the matching user.

After you have found the corresponding user in the Directory, press Apply, and then Close.

If you subsequently reload the permissions page, you will see that the Principal has been updated.

Related Articles
Article: Doc28 (permalink)
Date: March 22, 2008; 3:47:38 PM EDT
Author Name: Documentation Importer
Author ID: importer