User Management Guide

Chapter 2 Directory Subsystem: Authentication

This chapter describes the Directory subsystem of SilverStream eXtend Director. The Directory subsystem allows Director to integrate with the application server authentication mechanism.

This chapter contains the following sections:

For more information For an overview of the Directory subsystem, see The Directory subsystem.

About authentication

Authentication is the process of verifying the identity of a user who is requesting access to protected resources. Authentication is typically performed by obtaining a user name and password and checking them against the list of users in your authentication realm. Authentication is performed by your application server through either an internal server realm or an external realm like Windows NT or LDAP. The Directory subsystem also includes an API to add, modify, and delete users and groups.

The Directory subsystem provides these services to the other Director subsystems, relieving them of having to know about the application server-specific APIs available for authentication. This allows Director applications to be portable across application servers, as the Directory subsystem acts as a layer of abstraction to some of the J2EE application server's idiosyncrasies.

JAAS

The JAAS (Java Authentication and Authorization Services), now part of the J2EE 1.3 specification, is used in applications to authenticate users and enforce access controls—but is not currently implemented by all application servers that Director supports. The Directory subsystem will leverage JAAS when available for the authentication process. Since JAAS does not provide APIs to manage principals (users and groups), the Directory subsystem enhances the application framework by providing a common API for managing them.

About realms

A security realm is an object that provides an interface to a back-end authentication mechanism, typically a directory server that provides persistence for user and group information (LDAP, Windows NT, NIS+, and so on).

An application built with Director can be configured to use one or two realms: readable and/or writable. The default is one writable realm:

Writable realm

In a writable (readable/writable) security realm, administrators can use the Directory subsystem to add, delete, and modify user and group entries.

A writable realm is useful when you want to allow anonymous users to "register" or to "create accounts" for themselves. For example, Internet sites often allow users to register and set up personalization.
Readable realm

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

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

Supplied realms

The Directory subsystem provides four predefined security realms:

SilverStream realm

This realm is for the SilverStream eXtend Application Server, which has providers for several readable realms as well as the SilverUsers readable/writable realm defined in the SilverMaster database (LDAP, Windows NT, and NIS+).

The Director EbiSilverServerRealm interface provides access methods to the SilverServer realm API.

authSilverStream

SilverStream compatibility realm

This realm exists for compatibility with SilverStream 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 SilverStream realm's SilverUsers directory as its user repository.

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 Director EbiWebLogicRealm interface provides access methods to the WebLogic server realm API.

authWebLogic

IBM WebSphere realm

This realm is for IBM WebSphere 4.x. 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 Director database.

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

authWebSphere

Pluggable realms

You can implement your own security realm to directly access a directory server—or you can rely on an existing database structure. You can easily create a custom security realm by implementing one or two Java interfaces that include a few dozen methods (EbiRealm or EbiWriteableRealm).

Configuring realms

You can configure custom realms using the eXtend Workbench graphical editors for services.xml and config.xml files as shown below. This chapter describes the process in terms of the XML source files.

services xml graphical

DirectoryConfig

Configuring an external readable realm in the SilverStream server

By default, the writable realm for the SilverStream server is SilverUsers. You can optionally configure your readable realm to be Windows NT, LDAP, or NIS+, while keeping SilverUsers as your separate writable realm.

Procedure To configure an external readable realm in SilverStream:

In Workbench open your project's Directory subsystem configuration file, located at:

... \library\DirectoryService\DirectoryService-conf\config.xml

Find the appropriate property:

NT property:

  <!--
     <property>
        <key>DirectoryService/realms/readable/params/PROVIDER</key>
        <value>NTSecurity</value>
     </property>
     <property>
        <key>DirectoryService/realms/readable/params/AUTHORITY</key>
        <value>MyDomain</value>
     </property>
  -->

LDAP property:

  <!--
     <property>
        <key>DirectoryService/realms/readable/params/PROVIDER</key>
        <value>LDAPSecurity</value>
     </property>
     <property>
        <key>DirectoryService/realms/readable/params/AUTHORITY</key>
        <value>MyServer</value>
     </property>
  -->

NIS+ property:

  <!--
  <property>
        <key>DirectoryService/realms/readable/params/PROVIDER</key>
        <value>NISPLUSSecurity</value>
     </property>
     <property>
        <key>DirectoryService/realms/readable/params/AUTHORITY</key>
        <value>MyServer</value>
     </property>
  -->

Remove the comment tags () surrounding the <property> tag for the appropriate realm.
Add the appropriate property value:

For NT: Change MyDomain to the domain you want to use.

For LDAP and NIS+: Change MyServer to the server you want to use.

By default, the readable realm is your primary realm. For API method calls, the Directory subsystem checks the primary realm first. If you want SilverStream (the writable realm) to be your primary realm, uncomment the following property:

  <!-- Uncomment only if you want to override the default behavior and
       define the writable realm as the primary realm -->
  <!--
        <property>
        <key>DirectoryService/realms/primary</key>
        <value>DirectoryService/realms/writeable</value>
     </property>
  -->

Open your project's Directory subsystem descriptor:

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

Find the following service property:

  <service>
     <interface>com.sssw.fw.directory.api.EbiSilverServerRealm</interface>
     <impl-class>  
         com.sssw.fw.server.silverserver.realm.EboSilverServerRealm
     </impl-class>
        <description>SilverStream realm</description>
        <max-instances>0</max-instances>
        <startup>M</startup>
     </service>

Set max-instances to 0.
NOTE This is very important so that the readable realm and writeable realm are separate instances of the EboSilverServerRealm implementation.
Redeploy your project.

Configuring readable and writable realms in WebLogic and WebSphere

Director provides one pluggable realm each for WebLogic and WebSphere. You can configure this realm as readable and writable through the Directory subsystem. To use a separate readable realm, you must implement your own pluggable realm.

To implement 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).

Procedure To configure a pluggable realm in WebLogic or WebSphere:

In Workbench, open your project's Directory service descriptor, located at:

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

Make an entry like this in services.xml:

  <service>
     <!-- you can use any key here but by convention this is the fully    
     qualified interface -->
     <interface>com.acme.MyCustomRealmInterface</interface>
  
     <!-- this is the fully qualified implementation class -->
     <impl-class>com.acme.MyCustomRealmImpl</impl-class>
  
     <description>this is my custom realm</description>
     <max-instances>1</max-instances>
     <startup>M</startup>
  </service>

If you are planning to use this class as both readable and writable realm, or if you are using only one instance of the realm, set max-instances to 1. Otherwise, set it to 0 (for multiple instances).
Open your project's Directory Service configuration file, located at:

... \library\DirectoryService\DirectoryService-conf\config.xml

Enter a new property in config.xml that matches the key you entered in services.xml. It should look like this:

  <property>
     <key>DirectoryService/realms/readable</key>
      <!-- this is the key that you entered in services.xml -->
     <value>com.acme.MyCustomRealmInterface</value>
  </property>
  <!-- Enter the same key here if your realm is writeable. And if so set 'max-instances' to 1 in the services.xml -->
  <property>
     <key>DirectoryService/realms/writeable</key>
     <value>com.acme.MyCustomRealmInterface</value>
  </property>

Redeploy your project.

Changing realms

Realms are not restricted to the application server on which the Director application is deployed. You can specify different pluggable realms after deploying your project.

For more information, see the section on deploying a Director EAR in the Core Development Guide.

Using the Directory API

The Director core components include an interactive login page that you can customize and use in your applications. You can use the core PortalLogin component as a template for developing your own login mechanism.

LoginComponent

This component requires users to provide a user ID and password in order to be authenticated by the server for a specified realm.

The code gets the user's UID (user identifier) and password from the entries on the login form. These values are used later to authenticate the user.
The code then verifies that there is no authenticated user in the current security context. The isAnonymous() method takes the EbiContext passed in from the component, and returns true if there is no authenticated user in the current security context.
Next the code gets a directory delegate to access methods for the configured realm. The EbiDirectoryDelegate is the main interface you need to access realms.
Finally, the code calls authUserPassword(context, userid, password) to authenticate the specified user. If it successfully authenticates the user, it returns a principal for the authenticated user; otherwise, it returns a null.

If you have configured more than one realm, this method authenticates the user by checking the primary realm first. If it fails, it checks the secondary realm.
NOTE You can also specify the realm using other versions of authUserPassword() on EbiDirectoryDelegate object. For more information, see the API Reference.

User Management Guide