by Elizabeth Bowling

Level: Intermediate Works with: LearningSpace Updated: 01-Aug-2002

LearningSpace supports several different approaches to adding and then authenticating users. You can add users manually through the user interface (UI), import multiple users in batch mode from a text file or from a Domino server's user directory, or even enable users to add themselves the first time they access LearningSpace. If you use one or more Collaboration servers, you can import the users automatically from the Core server to ensure the information is synchronized. You can additionally enable the Single Logon feature to enable users to move among Collaboration servers without logging on again and again.

This article presents a technical description of these features in LearningSpace 5.0.1. It explains the various methods available for adding users to LearningSpace and authenticating them upon logon. This article assumes that you're familiar with the LearningSpace architecture as well as the basic concepts and terminology used in LearningSpace. For more information about the LearningSpace architecture, see the LDD Today article "Understanding the architecture of LearningSpace."

Let's start by looking at the three major methods for adding users to LearningSpace and how those users are then authenticated at logon—first on the Core server and then on the Collaboration server. We'll wind things up with a look at the Single Logon feature in LearningSpace, which streamlines user authentication among multiple Collaboration servers.

Creating users in LearningSpace
Users can't enroll in LearningSpace-based courses—or access any LearningSpace features—until you add them to the LearningSpace database. (This is also known as rostering users.) When you create user records, you must assign each user some level of permissions, which determine what features the user can access. You can assign passwords at this time, or you can allow users to create their own passwords later.

Allowing users to self-roster
If you want users to create their own user records, you can enable self-rostering. When they self-roster, users are assumed to be students and are automatically assigned that User Type, along with its default set of permissions. You can modify permissions for a user or for all users within a particular User Type, at your convenience. Enabling the self-rostering feature saves you the work of adding users yourself; however, it puts the burden of creating appropriate logon names and passwords on the users. You may decide to add the new users yourself so that you can ensure the user records are created properly. You can add users either one at a time or in batches.

Adding one user at a time
If you only need to add a couple of users, you might as well do it manually through the Core server's Users module, where you can simply fill in a form for the new users. The drawback to this approach is that you can only create one user record at a time and you must submit it to the server before adding the next user. To add a user using this method:

1. On the Core server, navigate to the Users module.
2. Click Add and enter a logon name and password, and then assign permissions for that user.
3. Click OK to submit the new user record.
   
   

If you have more than a couple users to add, you'll find it easier to work in batch mode.

Adding users in batches
Adding users in batch mode involves importing the user information from a text file that you create. Creating a text file is simple: use any text editor to create a delimited file that contains one user record per line. LearningSpace supports several delimiters; the default delimiter is a space, but you can also use tabs, commas, and quotation marks to separate your fields. If you leave a field blank, indicate this with empty quotation marks (""). For example, the text file in the following screen doesn't include the email address for each user, so that field is represented with "".

If you are using the text file to add a lot of users at once, you might not want to bother creating unique passwords for each user. Instead, you can assign them all the same temporary password and allow users to customize their password themselves when they log on. (Note that you cannot leave the passwords blank.)



You still work through the Users module to import users, but the procedure is different:

1. On the Core server, navigate to the Users module and click Import.
2. On the Setup page, enter the file name to be imported and select the delimiters used in it, and then click Next.
   
   
   
3. On the Preview page, map the fields in your file to LearningSpace fields by selecting a field name at the top of each column.
   
   
   
4. Click Next to complete the process. Once the users have been imported, a Summary screen displays statistics about the operation.
   
   
   
5. Click Finish to return to the Users module.
   

How are LearningSpace users authenticated?
LearningSpace is accessed via the Core server. Once a user is registered in LearningSpace (that user has a valid record in the LearningSpace database), he or she must be authenticated against the LearningSpace database with every logon to the Core server. The user enters his or her logon name and password, and the pair are validated against the database. If no record can be found containing the same logon name with the specified password, the user is denied access. The LearningSpace database must be available during authentication; if the database cannot be accessed, authentication fails immediately.

Importing users from Domino
If your company uses Lotus Domino, you can import users from the server's Domino Directory (Address Book) into LearningSpace. This not only saves you the effort of manually adding or importing a large number of users, but it also enables you to keep your list of LearningSpace users synchronized with your list of Domino users. The Domino User Import feature can be used once to populate LearningSpace or periodically to keep LearningSpace up-to-date with your Domino user base. What it cannot be used for is updating the Domino Directory from LearningSpace—the import operation only works one way. This safeguards the integrity of your Domino Directory.

You import users from Domino by setting up the Domino User Import database on your Domino server, using it to extract user information from the Domino Directory, and then passing that information to LearningSpace. If you replicate the Domino Directory among multiple Domino servers, you only put the Domino User Import database on one server and import data from that copy of the Directory.

You enable the Domino User Import feature in three phases:

• Setting up the Domino User Import database
• Mapping Domino fields to LearningSpace fields
• Connecting LearningSpace and Domino

Setting up the Domino User Import database
First, you set up the Domino User Import database for use with LearningSpace:

1. Enable the database agents included with the Domino User Import database.
2. Electronically sign the database to ensure it has proper access to the Domino Directory.
3. Modify Domino server settings as needed to ensure the database agents can run.

If you're not familiar with these procedures, ask your Domino administrator for help.

Mapping Domino fields to LearningSpace fields
To ensure that data imported from Domino is correctly stored in LearningSpace, you'll need to map fields between the two applications. You do this by editing the Domino User Import database's Settings page, where you can define which users should be imported from Domino into LearningSpace and how data fields should map between the two. Here's an example of the Settings page:



For example, you'll probably want the First Name and Last Name fields in Domino mapped to the First Name and Last Name fields in LearningSpace—but you don't have to map them that way. Although the fields are mapped by default, you can change the mapping to suit your needs. You can additionally create default values for fields in LearningSpace that have no corresponding field in the Domino Directory, such as the LearningSpace Profile field.

Connecting LearningSpace and Domino
Finally, you need to set up LearningSpace to import the Domino users, using the Directory Settings page in the Core server's Home module. Use this page to create the connection between the Domino server and the LearningSpace Core server and to initiate (or schedule) the actual import:

1. On the LearningSpace Core server, navigate to the Home module and click the Directory Settings tab.
2. In the Server Access Information section, fill in the fields to define the connection between your Domino server and your LearningSpace Core server. The Protocol, Domino Host Name, Administrator Name, Administrator Password, and File Name and Path to Domino User Import Database fields are all required.
   
   
   
3. In the Import Settings section, fill in the Interval fields to schedule automatic user import and initiate the first import by clicking the Import Now button, if you wish. Then click Apply.
   
   

How are Domino-based users authenticated?
Domino stores user passwords in a hashed format; LearningSpace can't do that. In order to support Domino passwords in LearningSpace, users imported from Domino must be authenticated in Domino. When a user whose record was imported from Domino logs on to LearningSpace, his or her logon name and password are authenticated directly against the Domino Directory using the field mapping that was specified for the original user import. This approach requires that the Domino server be available for authentication even when you're not actually importing additional users from it, but it enables Domino users to retain their existing user names and passwords for use in LearningSpace.

Adding users on a Collaboration server
As we learned earlier, a user logs on to the Core server to access LearningSpace in general. To access any of the collaborative features in LearningSpace, he or she must additionally log on to the Collaboration server where those features are hosted. The Collaboration component of LearningSpace runs on a Domino engine, so it uses Domino authentication technology, including the storage of passwords in a hashed format. This requires it to maintain its own Domino Directory and authenticate users against that, rather than against the LearningSpace database, which cannot store passwords in this manner. Thus, you must maintain a duplicate copy of user records on each Collaboration server.

The records aren't actually "duplicated"; the Collaboration server needs only enough information to authenticate users for logon (specifically, logon name and password). Once the user has successfully logged on to LearningSpace on the Collaboration server, additional user information, such as which courses the user is enrolled in, is pulled from the LearningSpace database via the Core server. Still, you need to get basic user information (logon names, passwords) from the LearningSpace database over to the Collaboration server. You do this with the Collaboration Synchronization feature.

Collaboration Synchronization
Collaboration Synchronization lets you propagate user information from the LearningSpace database to a Collaboration server. This feature removes the need for you to re-enter user information on the Collaboration server. It also provides you the additional benefit of ensuring that the user information stored in the Collaboration server is kept in sync with that stored in the LearningSpace database. For example, if you change a user's password using the Core server's Users module, the Collaboration Synchronization feature will change that user's password in the Collaboration server's Domino Directory, keeping the Person document up-to-date.

You synchronize users between the Core and Collaboration servers by importing information from the LearningSpace library to the Collaboration server's Domino Directory using the Collaboration Sync database as the intermediary. This database resides on the Collaboration server; it is installed automatically with the Collaboration component. All you need to do is create the connection between the Core and Collaboration servers, using the Collaboration Settings page in the Core server's Home module. Once the connection is working, you simply enable the Collaboration Synchronization feature. You can use this feature to perform a one-time user import from the LearningSpace database to the Collaboration server, but you'll probably want to set it up to run periodically to ensure that user records are kept up-to-date on the Collaboration server.

If you use only one Collaboration server, you can synchronize users directly with the Core server. If you use multiple Collaboration servers, configure them as a LearningSpace community (similar to a Domino domain) and use Domino replication to share the user information among them. One Collaboration server in the community, known as the Collaboration Synchronization server, contains the master copy of the Domino Directory and receives updates from the LearningSpace database via the Core server. That Collaboration server then replicates the Domino Directory out to each remaining Collaboration server in the community, ensuring that they all stay synchronized.

How are Collaboration users authenticated?
A Collaboration server uses a Domino Directory for its user directory and authenticates users in the same manner as Domino. LearningSpace users are represented in the Domino Directory with Person documents. When a user logs on to a Collaboration server, his or her logon name and password are compared with the Person documents. If no Person document can be found containing the same logon name with the specified password, the user is denied access.

In addition, the Domino Directory maintains Group records listing users who have access to LearningSpace Discussion forums (a special form of Notes database) stored on the current Collaboration server. Whenever a LearningSpace user is given permission (on the Core server) to access a Discussion, the Collaboration Synchronization operation sends an update to the Domino Directory on the Collaboration server where the Discussion is stored, and the user's name is added to the appropriate Group record in the Directory.

LearningSpace users always log on to the Core server. If a user then needs to access collaborative features (hosted on a Collaboration server), he or she must additionally log on to the appropriate Collaboration server. If your installation includes multiple Collaboration servers, the user must log on to each as needed, even if the Collaboration servers are configured as a community and replicate a single Domino Directory among themselves.

To simplify user access, you can enable the Single Logon feature, which enables a user to log on once on the Core server and then be authenticated automatically whenever he or she accesses any Collaboration server.

Using Single Logon to authenticate users
The Single Logon feature in LearningSpace enables a user to log on to LearningSpace once via the Core server, and gain immediate access to all of the installation's Collaboration servers without being required to log on again. To take advantage of this feature, users must already have been added to LearningSpace using one of the methods described previously.

Without Single Logon, authentication is performed differently depending on how users were added to the LearningSpace database. Suppose a user logs on to the Core server; if that user's record was initially imported from a Domino server, he or she is authenticated against that Domino server's Directory when logging on to Core, and against the Collaboration server's Directory when logging on to any Collaboration server. If that user was added directly in LearningSpace, then he or she is instead authenticated against the LearningSpace database when logging on to Core, but is still authenticated against the Collaboration server's Directory when logging on to any Collaboration server. Core servers authenticate against the system where the user was created, while Collaboration servers always authenticate against their own Directories.

When you enable Single Logon, all authentication is performed against the Collaboration Synchronization server’s Directory, using Domino’s Web Single Sign On technology. No matter which LearningSpace server a user logs on to, he or she is authenticated against the Collaboration Synchronization server, where the authentication token is physically stored.

The user still accesses LearningSpace by logging on to the Core server and then accesses features on other servers from there. When the user logs on to the Core server with Single Logon enabled:

1. An authentication request is sent to the Collaboration Synchronization server.
2. An authentication token is generated (assuming the request is successful).
3. A cookie containing the authentication token is passed back to the user’s browser.

Each time that user accesses a LearningSpace server during the session, the cookie is made available to the new server, which checks the authentication token before allowing the user access. The cookie is deleted when the user closes the browser or when the cookie's time-limit expires.

The basic requirement of the Single Logon feature is that Collaboration Synchronization be enabled, with the Collaboration Synchronization server registered on the Core server. If you use multiple Collaboration servers in a community, the "Web SSO" document in the Collaboration Synchronization server's Domino Directory must list each server within the community for which Single Logon should be enabled. Only the Collaboration servers listed in this document will validate the cookie containing the authentication token and allow access without an additional logon.

Handle with care!
Although the Single Logon feature makes use of the Domino Web Single Sign On technology, it is intended only for use with LearningSpace servers and is not supported with non-LearningSpace servers, even though they may also use Domino technologies.

In addition, the Single Logon feature requires that all authentication be performed against a single Collaboration server. If that server is unavailable, nobody can access LearningSpace. This restriction demands extra care when adding and removing Collaboration servers within your LearningSpace installation.

For example, when you install Collaboration servers into an existing community, you must take the Collaboration Synchronization server out of service long enough to update its Domino Directory with information about the new server. If Single Logon is enabled when you do this, nobody will be able to authenticate against the Collaboration Synchronization server while it is out of service. To prevent this problem, you’ll have to disable the Single Logon feature while you work on the Collaboration Synchronization server; you can re-enable Single Logon when the Collaboration Synchronization server comes back on-line.

Finally, if you allow users to self-roster when Single Logon is enabled, be aware that there is a delay before they can be authenticated by the Collaboration server, as the Domino Directory requires some time to update. This delay might be as short as a minute or as long as a half hour, depending on the size of the Domino Directory and what else is being processed on the Collaboration server at the same time. If a user self-rosters on the Core server and then immediately attempts to log on, authentication will probably fail. You should warn your users to wait a half hour or so before attempting to log on.

Putting it all to work
As we've seen, there are a variety of methods for adding users to LearningSpace and authenticating them at logon. While implementing some of these features may take some work, they make it easier for you to add new users to LearningSpace and for those users to access all of the LearningSpace features.

If your company uses Lotus Domino, it makes sense to take advantage of existing user records by importing users from the Domino Directory directly into LearningSpace; otherwise, you should either export data from another application and create a text file that you can import into LearningSpace or simply enable self-rostering within LearningSpace so that users can add themselves. While it's simple enough to add a user by hand, you wouldn't want to do it all day!

If you use Collaboration servers in your installation, enable the Collaboration Synchronization feature to copy user information from the LearningSpace database and ensure that the data remains up-to-date. Enabling this feature additionally gives you the option of using Single Logon to ease user access to multiple Collaboration servers, so users don't have to log on every time they move to another server. Remember that Single Logon is dependent upon Collaboration Synchronization and should not be enabled until the Collaboration Synchronization server's Directory is in sync with the LearningSpace database.


ABOUT THE AUTHOR
Elizabeth Bowling is a technical writer for IBM's Lotus Software division. Over the past 13 years, Elizabeth has produced application design, programming, and system administration documentation for a variety of Lotus products, including Notes, LotusScript, and LearningSpace.