User Management Guide

CHAPTER 1

About Pluggable Realms

This chapter summarizes the pluggable realm implementations of exteNd Director and provides information about configuring realms. It has these sections:

NOTE: For more information For information about configuring realms, see the section on directory configuration in Developing exteNd Director Applications.

About realms

A realm is an exteNd Director application's interface to a persistent repository of users, groups, and passwords. In an exteNd Director application, a realm is a class that implements the interface EbiRealm or EbiWritableRealm.

Types of realms

These are the types of pluggable realms:

Realm type	Description
LDAP realm	Provides an interface to the Novell eDirectory LDAP server. Typically this is a writable realm. Support for eDirectory actually consists of several realms: a base LDAP realm plus LDAP realms specific to the exteNd Application Server, BEA WebLogic, and IBM WebSphere. NOTE: You cannot use exteNd Director to add or remove containers or custom user attributes in an LDAP realm. Those operations require you to use the LDAP server's own administration interface.
J2EE application server realm	Provides a uniform, platform-independent interface to vendor-specific authentication and user/group management APIs. Can be a readable or writable realm. The actual authentication mechanism can be internal or external to the application server. From a programming standpoint, this is entirely transparent to your application. For example, if you are using the Novell exteNd Application Server, you can change the authentication provider from Windows NT to NIS+ by making only configuration changes; no code changes are needed.
PersistManager realm	Uses the exteNd Director database as a user/group repository and does its own authentication using a user/password pairing accessed from the database. Typically it is a a writable realm.
Compatibility realm	Provides an interface to an internal authentication API used in previous versions of exteNd Director. Users and groups are stored in an exteNd Director application database. Must be a writable realm. Not recommended for new applications.

Realm access

Realms can be either readable (read-only) or writable (read-write) as described below. For details about each realm, see the section on directory configuration in Developing exteNd Director Applications.

Realm access usage	Description
One readable (read-only) realm	In a readable realm, the Directory subsystem cannot add new users or groups or modify existing ones. A readable realm is useful when you want full control over the users and groups that can access an application. For example, intranets often use a central administration application to manage all users and groups.
One writable (read-write) realm	In a writable realm, administrators can use the Directory subsystem to add, delete, and modify users and groups. A writable realm is useful when you want to allow anonymous users to add themselves to the realm. For example, Internet sites often allow users to register or create accounts for themselves.
One readable realm and one writable realm	An application with two realms can use each realm for a different purpose. For example, an corporate portal application might use a readable realm for employees and a writable realm for customers.

Realm access usage

Description

One readable (read-only) realm

In a readable realm, the Directory subsystem cannot add new users or groups or modify existing ones.

A readable realm is useful when you want full control over the users and groups that can access an application. For example, intranets often use a central administration application to manage all users and groups.

One writable (read-write) realm

In a writable realm, administrators can use the Directory subsystem to add, delete, and modify users and groups.

A writable realm is useful when you want to allow anonymous users to add themselves to the realm. For example, Internet sites often allow users to register or create accounts for themselves.

One readable realm and one writable realm

An application with two realms can use each realm for a different purpose.

For example, an corporate portal application might use a readable realm for employees and a writable realm for customers.

J2EE application server realms

This section describes the pluggable realm implementations for supported J2EE application servers (non-LDAP).

exteNd Application Server realm

This realm uses the exteNd Application Server Directory APIs and can be configured to use LDAP, Windows NT, SilverUsers, and NIS+ security providers. The LDAP and Windows NT security providers are read-only.

NOTE: If you are using eDirectory on the exteNd Application Server, it is recommended that you use the exteNd LDAP realm.

The EbiSilverServerRealm interface provides access methods to the exteNd Application Server realm:

Interface:

EbiSilverServerRealm

Implementation:

EboSilverServerRealm

Authentication provider:

SilverSecurity (default)

NTSecurity

LDAPSecurity

NISPLUSSecurity

authSilverStream

exteNd application server compatibility realm

This realm exists for compatibility with ePortal 2.x directory services or any application that requires nested groups. It uses a set of database tables for user and group bindings. It also uses the exteNd Application Server realm's SilverUsers directory as its user repository:

Interface:	EbiUserManagerRealm
Implementation:	EboUserManagerRealm
Authentication provider:	SilverUsers

BEA WebLogic realm

This realm is for BEA WebLogic 6.x. It calls the underlying server API to provide readable access to external realms (LDAP and Windows NT) and readable/writable access to the default realm stored in the file system on the application server.

The exteNd Director EbiWebLogicRealm interface provides access methods to the WebLogic server realm API:

authWebLogic

Interface:	EbiWeblogicRealm
Implementation:	EboWeblogicRealm
Authentication provider:	WebLogic internal store

IBM WebSphere realm

This realm is for IBM WebSphere 4.x and 5.x. exteNd Director accesses data through a custom registry based on a relational database to provide directory services. (IBM WebSphere does not provide a realm-access API other than authentication.) All method calls go through the exteNd Director database.

For authentication, the exteNd Director EbiWebSphereRealm interface calls the WebSphere authentication method, which in turn calls through to the database:

authWebSphere

Interface:	EbiWebsphereRealm
Implementation:	EboWebsphereRealm
Authentication provider:	AUTHUSERS (exteNd Director internal store)

LDAP server realms

For writable LDAP realms, exteNd Director provides:

A generic base class that implements the Java Naming Service Interface (JNDI) (JNDI is the standard way in Java to access an LDAP realm hierarchy)
A derived class for each supported J2EE application server to authenticate users using a Novell eDirectory LDAP realm.Base LDAP realm

Base LDAP realm

The JNDI realm base class provides an administrator connection to the LDAP server for retrieving groups and users. This connection is internal, and thus unauthorized external access to data is prevented. A user's JNDI connection is stored as part of the user session when the user is authenticated through the realm:

authLdapAppServer

LDAP application server realms

The base class supports generic LDAP authentication only and does not provide authentication through an application server. This latter is provided by a separate class for each application server. The application server realm overrides the authenticate method in the JNDI realm super class and uses the Application Server API for authentication

PersistManager realm

This is a generic realm that can be used to access users and groups directly from the exteNd Director database using the Directory subsystem API. It does not rely on any native application server APIs:

authPersistManager

Interface:	EbiPersistMgrRealm
Implementation:	EboPersistMgrRealm
Authentication provider:	AUTHUSERS (exteNd Director internal store)

Writing a custom realm

You can implement your own realm to directly access a directory server—or you can rely on an existing database structure. You can create a custom security realm by implementing these interfaces in the com.sssw.fw.directory.api package:

Directory class	Description
EbiRealm	Interface that custom realms need to implement if they want to provide read-only directory services. The directory manager loads instances of realms that implement this interface as well as the subinterface EbiWriteableRealm.
EbiWriteableRealm	Interface that custom realms need to implement if they want to provide write access in the directory service. The directory manager loads instances of realms that implement this interface as well as the superinterface EbiRealm.
EbiRealmUser	The wrapper principal used by custom realms. The original principal implementation can be used internally in order to leverage existing principal functionality and APIs.
EbiRealmGroup	The wrapper group principal used by custom realms. The original principal implementation can be used internally in order to leverage existing principal functionality and APIs.

For more information, see Configuring a custom realm.

Configuring realms

You can configure the realm used in an exteNd Director application automatically or manually.

Configuring realms automatically

You can configure the realm used in an exteNd Director application in the exteNd Director development environment using either of the following tools, which perform exactly the same function:

exteNd Director Project Wizard—for new projects

For a full description of the wizard, see the section on creating a project in Developing exteNd Director Applications.
exteNd Director Configuration Tool—for existing projects

For a full description of the tool, see the section on reconfiguring an exteNd Director application in Developing exteNd Director Applications.

Configuring realms manually

Two descriptor files contain editable key/value pairs representing your application's realm and Directory subsystem configuration properties. The files are located in your project tree in the DirectoryService-conf folder.

Descriptor	Contents	For information, see
config.xml	Realm configuration properties	The section on changing configurations in Developing exteNd Director Applications
services.xml	Directory subsystem service configuration

Configuring a different authentication provider

This section applies to exteNd Application Server realms only.

The default realm for the exteNd Application Server is SilverUsers. You can reconfigure your realm to be any of the authentication providers supported by the exteNd Application Server, including Windows NT and NIS+.

Procedure To configure a different authentication provider:

In exteNd Director, open config.xml for the Directory subsystem:
Click Add.
For each key/value pair, double-click the Key field and the Value field and enter these values:

For Windows NT:
- Key: DirectoryService/realms/readable/params/PROVIDER
- Value: NTSecurity
- Key: DirectoryService/realms/readable/params/AUTHORITY
- Value: Your NT realm domain
For NIS+:
- Key: DirectoryService/realms/readable/params/PROVIDER
- Value: NISPLUSSecurity
- Key: DirectoryService/realms/readable/params/AUTHORITY
- Value: Your NIS+ server
NOTE: If you want to reconfigure your primary realm, see Configuring the primary realm.
Redeploy your project.

For deployment information, see the chapter on deploying an exteNd Director project in Developing exteNd Director Applications.

Configuring the primary realm

By default, the readable realm is the primary realm. For API method calls, the Directory subsystem checks the primary realm first.

Procedure To specify your writable realm as the primary realm:

In exteNd Director, open config.xml for the Directory subsystem.
Click Add.
Enter this key/value pair:
- Key: DirectoryService/realms/primary
- Value: DirectoryService/realms/writable

Open your project's Directory service descriptor:

  ...\library\DirectoryService\DirectoryService-conf\services.xml

services xml graphical

Click Add.

Enter the values as shown:

Form information	Value
Interface	com.sssw.fw.directory.api.EbiSilverServerRealm
Implementation Class	com.sssw.fw.server.silverserver.realm.EboSilverServerRealm
Maximum Instances	0 IMPORTANT: You must set Maximum Instances to 0 so that the readable realm and writable realm are separate instances of the EboSilverServerRealm implementation.
Startup	manual
Description	Any string

Redeploy your project.

For more information, see the section on deploying an exteNd Director project in Developing exteNd Director Applications.

Configuring a custom realm

To write a custom pluggable realm, you need to implement the interface com.sssw.fw.directory.EbiRealm (for a readable realm) or EbiWriteableRealm (for a writable realm).

For more information, see Writing a custom realm.

Procedure To configure a custom realm:

In exteNd Director, open services.xml for the Directory subsystem.
Click Add.

Enter the appropriate values:

Form information	Description
Interface	A key for the interface or the fully qualified name. For example: com.acme.MyCustomRealmInterface.
Implementation Class	The fully qualified implementation class. For example: com.acme.MyCustomRealmImpl.
Maximum Instances	Set this value to 1 if you are planning to use the class as both readable and writable realm or if you are using only one instance of the realm. Otherwise, set it to 0 (for multiple instances).
Startup	If you want the class instantiated on server startup, select automatic. Otherwise, select manual.
Description	Any string.

In exteNd Director, open services.xml for the Directory subsystem.
If your realm is readable-only, enter a key/value pair that matches the value you entered in services.xml:
- Key: DirectoryService/realms/readable
  
  Value: Your readable realm interface. For example: com.acme.MyCustomRealmInterface
If the custom realm is readable/writable, add the same value with this key:
- Key: DirectoryService/realms/writable
  
  Value: Your readable/writable realm interface. For example: com.acme.MyCustomRealmInterface
Redeploy your project.

For more information, see the section on deploying an exteNd Director project in Developing exteNd Director Applications.