User Management Guide

CHAPTER 2

Managing Users and Groups

This chapter describes how to manage realm users, groups, and LDAP containers. It has these sections:

• About the Directory subsystem

• Authenticating users

• Adding users and groups

• Accessing users, groups, and containers

About the Directory subsystem

The Directory subsystem is used to manage readable and writable realms that you have configured using the exteNd Director Project Wizard. To facilitate authorization and other user-based operations within a realm, the Directory subsystem supports the concepts of users and groups. In the case of an LDAP realm, the Directory subsystem also supports the concept of containers and subcontainers.

Directory API

The Directory API provides complete programmatic access to users, groups, and containers. Users, groups, and containers are associated with java.security.Principal. A principal is used to authorize access to application resources.

    For more information, see Using ACL-Based Authorization.

These are the key Directory subsystem classes:

Authenticating users

Authentication is performed by obtaining a user name and password and checking them against a list of registered users in a directory realm. Knowledge of a registered user ID and the corresponding password is assumed to guarantee that a user is authentic.

Each user registers initially (or is registered by an administrator), using an assigned or self-declared user ID and password. On each subsequent use the user must use the previously declared user ID and password.

When a user of an exteNd Director application successfully authenticates, exteNd Director obtains the list of group and LDAP container memberships for that user and keeps the list available for the duration of the user's session. The list is used for the purpose of authorization when the user attempts to access a protected resource.

About the Login portlet

The Portal subsystem provides a core portlet (Portal Login) for the purpose of user authentication. Portal applications generated by the Project Wizard use this portlet by default

The PortalLogin portlet works out of the box for many applications. Therefore, you may want to use it as is in your Portal application. However, you can also customize it to meet your own requirements, if you like.

Where to find the sources   The sources for this portlet are located in your exteNd installation directory at: Director/templates/TemplateResources/portal-core-resource.

Simultaneous logout from exteNd Director and iChain

You can configure iChain to act as a proxy server for exteNd Director. In this configuration, the user can login to exteNd Director through iChain. In addition, the user can logout of both iChain and exteNd Director simultaneously. When a user attempts to logout of both exteNd Director and iChain, exteNd Director sends a redirect back to the iChain server. This instructs iChain to end its session and display a logout page.

NOTE:   To work with iChain, exteNd Director must be using the same eDirectory realm as the iChain server.

To support simultaneous logout from exteNd Director and iChain, you need to make some simple configuration changes in both products.

Configuring exteNd Director to work with iChain   The config.xml file for the Directory subsystem provides two properties that let you provide support for simultaneous logout with iChain:

  https://myiChainServer/cmd/BM-Logout

Configuring iChain to work with exteNd Director   The iChain server needs to be configured so that it enables authentication and forwards both the authentication parameters and the iChain cookie. The iChain cookie name is a uniquely generated character string that is 16 characters long beginning with the string IPCZQX0.

To configure iChain to work with exteNd Director, you need to follow these steps:

1. Click the Configure button in the iChain administration tool.

2. Select Web Server Accelerator.

3. Click the Modify button.

4. Click the Authentication Options button.

5. Select the Forward iChain cookie to Web server option.

6. Select the Forward authentication information to Web server option.

Authenticating a user

This code shows how to authenticate a user:

  // Get a directory delegate.
  EbiDirectoryDelegate dirService = com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  // Initialize principal object.
  java.security.Principal prin = null;
  
  try {
      // Attempt to authenticate the user ID and password.
      prin = dirService.authUserPassword(context, uid, pwd);
  } catch (Exception ex) {}

Adding users and groups

This section describes how to use the Directory API to add users and groups to a configured realm. Adding users and groups automatically adds the associated principal object for assigning security ACLs.

Adding containers    You cannot add LDAP containers from the Directory API. Use your native LDAP realm tools for this purpose. However, you can access existing containers; see Accessing users, groups, and containers.

Adding users and groups using the DAC    You can also use the Director Administration Console (DAC) to add new users and groups. For more information, see Using the Directory Section of the DAC.

Adding users using the New User portlet   The Portal subsystem provides a core portlet called New User that allows anonymous users to register themselves. Portal applications generated by the Project Wizard use this portlet by default, and the DAC and CMS Administration Console both use customized versions of the New User portlet.

    for more information, see About the New User portlet.

Adding a user

To add a user, use the addUser() method on the EbiDirectoryDelegate object. You can also use methods on EboDirectoryHelper to get information about the user, as shown in the example that follows.

Example: checking the self-registration key   This code determines whether or not users are allowed to self-register:

  m_isLoginNewUsersEnabled = EboDirectoryHelper.isLoginNewUsersEnabled();

The property is set in the Directory subsystem config.xml file:

  <property>
      <key>com.sssw.fw.directory.LOGIN_NEW_USERS_ENABLED</key>
      <value>true</value>
  </property>

Example: adding the user to the realm   This code shows how to register a new user:

  // Get the context. Use this method or one of the others 
  // available on the factory object.
  EbiContext.context = com.sssw.fw.factory.getDirectoryDelegate()
  // Get directory delegate.
  EbiDirectoryDelegate delegate = com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  // Add the user.
      delegate.addUser(context, user, pwd);
  }

Adding LDAP users   For a writable LDAP realm you can specify the fully qualified name (Distinguished Name) or the common name. The API relies on the LDAP config parameters specified in the Project Wizard.

    For more information, see LDAP realm configuration in Developing exteNd Director Applications.

NOTE:   It is best to use the fully qualified name whenever possible. This avoids potential conflicts with users having identical IDs in separate containers.

Adding a group

To add a group to the writable realm, use the addGroup() method on the directory delegate:

  EbiDirectoryDelegate delegate = com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  // Add the user.
      delegate.addGroup(context, groupName);
  }

Adding a user to a group

To add a user to a group, use the addMember() method on a Group object:

  try {
  	 EbiDirectoryDelegate delegate =
  	 com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  
  	 Group group = delegate.getGroup();
  	 
  	 Principal user = delegate.getUser(context, username);
      group.addMember(user);
                              }
              return true;
  }
  catch (Exception e) { }
          return false;

Accessing users, groups, and containers

The directory delegate provides several methods for retrieving users and groups. See the getUsers() and get Groups() methods in EbiDirectoryDelegate. The realm container delegate has methods for accessing containers in tree realms like LDAP. See EbiRealmContainerDelegate.

Most of the methods described in this section return principals associated with the user, group, or container. This allows you to set security ACLs using the Security API.

    For more information, see Using ACL-Based Authorization.

User and group queries

The Directory API supports user and group queries for supported realm configurations. This feature allows you to include query strings to get filtered lists of users and groups. Using queries provides performance benefits, especially with large directories. The Directory API includes two classes to support queries:

• EbiDirectoryUsersQuery

• EbiDirectoryGroupsQuery

Some usage examples follow:

Example: user query    :

  // Get a directory delegate.
  EbiDirectoryDelegate delegate = com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  
  // Get the query object.
  EbiDirectoryUsersQuery query =EboFactory.getDirectoryUsersQuery();
  
  // Specify a query string.
  query.whereUserIDStartsWith(search_str);         
  if (!EboStringMisc.isEmpty(myRealm))query.whereRealmName(myRealm);
  if (!EboStringMisc.isEmpty(myGroup))query.whereGroupID(myGroup);
  
  // Get collection of EbiRealmUsers.
  Collection users =delegate.getUsers(context, query);
  // EbiRealmUser objects are returned.

Example: group query  

  // Get a directory delegate.
  EbiDirectoryDelegate delegate = com.sssw.fw.directory.client.EboFactory.getDirectoryDelegate();
  
  // Specify query strings.
  EbiDirectoryGroupsQuery query = getDirectoryGroupsQuery();
  query.whereGroupIDStartsWith(search_str);
  
  // To retrieve children of "root" groups only. query.whereParentGroupID(EbiDirectoryConstants.DIRECTORY_ROOT_GROUP);
  if (!EboStringMisc.isEmpty(myRealm))query.whereRealmName(myRealm);
  
  // Get a collection of EbiRealmGroups.
  Collection groups = delegate.getGroups(context, query); 
  // EbiRealmGroup objects are returned.

Dynamic groups support

The Directory subsystem supports accessing existing dynamic groups in eDirectory realms. Dynamic groups are an LDAP realm feature that allows groups to be defined dynamically by a query.

NOTE:   exteNd Director does not support the creation or modification of dynamic groups. Use your LDAP client tool for this purpose.

You need to configure your exteNd Director project to access dynamic groups.For more information, see the section on LDAP realm configuration in Developing exteNd Director Applications.

To access a dynamic group, use one of the getGroup() methods on EbiDirectoryDelegate. The delegate also has this method for determining dynamic group realm status:

  public boolean isDynamicGroupSupported(String realm)

    For more information about dynamic groups in eDirectory, go to:

http://developer.novell.com/research/appnotes/2002/april/05/a0204054.htm

Getting container principals in a tree realm

You can use container delegate methods to access container principals in an LDAP or similar tree-type realm.

NOTE:   Setting ACLs on a container principal allows you to apply security inheritance to users in the container hierarchy. For more information, see Accessing ACLs for containers.

This example shows how to get a root container and its descendants:

  // Intialize Java container object.
  Collection availContainers = null;
  // Get container delegate.
  EbiRealmContainerDelegate conDelegate = com.sssw.fw.directory.client.EboFactory.getRealmContainerDelegate();
  // Get the root (top) container.
  EbiRealmContainer root = conDelegate.getRootContainer(context);
  // Get Collection of EbiRealmPrincipals.
  EbiRealmContainer's and/or EbiRealmUser's)
  if (root != null) {
  
  
     availContainers = conDelegate.getDescendants(context, root, true, false);
        if (availContainers != null) {
           availContainers.add(root) ;
        }
        else {
           availContainers = new ArrayList();
           availContainers.add(root) ;
        }
  
     }
  
     return availContainers;
  }

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...