User Management Guide

CHAPTER 8    Configuring Authentication Realms

This chapter describes how to configure an authentication realm for your Director project. It has these sections:

• Realm configurations

• Configuring an LDAP realm

• About the configuration and services descriptors

• Configuring an external readable realm in exteNd

• Configuring a custom realm

• Editing or changing realms

    For background information about the Directory subsystem, see Understanding Authentication Realms.

Realm configurations

Director provides pluggable realms for supported J2EE application server vendors, as well as LDAP support. You select a realm when you create a new project using the Director Project Wizard in exteNd Workbench.

For most realm configurations (excluding LDAP realms), Workbench will automatically configure the realm based on your selection in the Wizard. For LDAP realms more setup is required, as described in Configuring an LDAP realm.

Here is the list of available realm configurations

Configuring an LDAP realm

An LDAP configuration allows you to integrate your Novell eDirectory LDAP realm with the Directory and User subsystems. You specify LDAP configuration properties when you create a project using the Director Project Wizard. These properties are described in LDAP directory configuration properties and LDAP user configuration properties.

You must also do the following before you deploy your project:

• Import the UUID auxiliary class provided with the Director install. See Configuring and using SSL for LDAP connections.

• Set up your LDAP server to use SS, if applicable. See Configuring and using SSL for LDAP connections.

LDAP directory configuration properties

When you select an LDAP realm using the Project Wizard in Workbench, you get this panel related to the Directory subsystem integration:

LDAP user configuration properties

When you select an LDAP realm using the Project Wizard in Workbench, you get this panel related to the User subsystem integration:

  auxclass1,attr1,attr2|auxclass2,attr1,attr2

Importing the UUID auxiliary class

Before you deploy a project that implements one of the LDAP application server realms, you need to import the provided auxiliary class specified in the UUID auxiliary class property. The purpose of this class is to add a UUID attribute that allows the Director and User subsystem APIs to access the LDAP realm.

You import this class using the NDS Import Wizard in the Novell ConsoleOne eDirectory tool.

To import the UUID auxiliary class in ConsoleOne:

1. With the NDS container selected in ConsoleOne, select Wizards>NDS Import/Export.

   

2. Click Import LDIF File and choose Next.

   

3. Navigate to the ldif file in your Director installation path and select it (it is located at bin/extElemImport.ldif). Click Next.

   

4. Verify the LDAP host name and port, choose Authenticated Login, and specify your administrator DN (distinguished name) and password.

   

5. Verify the information and click Finish.

   

Configuring and using SSL for LDAP connections

NOTE:   SSL connections are slower than plain or clear-text connections. The initial portal connection can take up to 30 seconds to be established.

To configure the LDAP server to support SSL:

1. In ConsoleOne, open the properties on the LDAP Server object that represents the LDAP server you are using with Director.

2. Select the SSL Configuration tab.

3. For the SSL Certificate field, select an SSL Certificate object.

4. Make note of the SSL Port (typically 636).

5. Make sure the Disable SSL Port option is not checked.

6. Save the settings and refresh the NLDAP server:

   1. Open the properties of the LDAP server.

   2. Press the Refresh NLDAP Server Now button on the General page.

To export the Trusted Root Certificate:

1. Open the properties on the SSL certificate object that you configured in the preceding procedure.

2. Select the Certificates tab.

3. Select the Trusted Root Certificate subtab.

4. Press Export and save the file in binary DER format, typically named TrustedRootCert.der.

To download and install the Java Secure Socket Extension (JSSE):

NOTE:   This step is required only if your server is running with a JRE older than 1.4 and is not already configured to use JSSE.

Follow the installation instructions for JSSE — summarized as follows:

1. Copy JSSE.JAR, JNET.JAR and JCERT.JAR to the server's JRE extensions directory (for example: jre/lib/ext).

2. Find and edit the java.security file, located in the lib/security directory of the server's JRE (for example: jre/lib/security/java.security).

3. Follow the directions at the beginning of the document to add the JSSE SSL provider:

   • Add a line to the security providers section using the format below, replacing name with the next provider number in succession:

     security.provider.name =com.sun.net.ssl.internal.ssl.Provider
   

To import the Trusted Root Certificate into your cacerts or jssecacerts trust store file:

1. Find the cacerts or jssecacerts file. It is located in the lib/security directory of the server's JRE (for example: jre/lib/security/cacerts).

2. Find keytool, located in the /bin folder relative to your Java home folder.

   NOTE:   You must use a keytool that comes with JVM 1.3 or higher.

3. Run the following command, making replacements listed below:

     keytool -import -alias aliasName -file TrustedRootCert.der -keystore cacerts -storepass changeit
   

   • Replace aliasName with a unique name for this certificate.

   • Make sure the full path for cacerts is specified and the full path for TrustedRootCert.der.

   • changeit is the default keystore password. Use the appropriate keystore password if it has been changed.

To configure Director to use SSL in the Directory Service:

1. Open your Director project in exteNd Workbench.

2. Select Project>Director Project>Configuration.

3. Click the Directory tab and then click Directory Ldap Options lower tab.

4. Change the LDAP host to include the SSL port for eDirectory (for example: localhost:636).

5. Make sure Use SSL is checked and then click OK.

6. Rebuild your project and redeploy.

About the configuration and services descriptors

When you complete the Project Wizard, Workbench generates two descriptors containing editable key/value pairs representing realm and Directory subsystem configuration properties:

Generally you only need to edit these files directly for special cases. See Editing or changing realms.

The descriptors are located in your project tree in the DirectoryService-conf folder in the DirectoryService.jar.

    For more information about where project files are located, see the section on Director project structure in the Core Development Guide.

Configuring an external readable realm in exteNd

This section applies to the non-ldap exteNd application server realm only.

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

NOTE:   If you are accessing an external LDAP realm through Novell eDirectory, the exteNd ServerLdap realm is the recommended LDAP configuration. See Configuring an LDAP realm.

To configure a different security provider in exteNd:

1. In Workbench, open config.xml for the Directory subsystem.

       For more information about where project files are located, see the section on Director project structure in the Core Development Guide.

   

2. Click Add.

3. 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 LDAP (read-only):

   NOTE:   If you are accessing an external LDAP realm through Novell eDirectory, the exteNd ServerLdap realm is the recommended LDAP configuration. See Configuring an LDAP realm.

   • Key: DirectoryService/realms/readable/params/PROVIDER

   • Value: NTSecurity

   • Key: DirectoryService/realms/readable/params/AUTHORITY

   • Value: Your LDAP server.

   For NIS+:

   • Key: DirectoryService/realms/readable/params/PROVIDER

   • Value: NTSecurity

   • Key: DirectoryService/realms/readable/params/AUTHORITY

   • Value: Your NIS+ server

   NOTE:   If you want to reconfigure your primary realm, see Configuring a primary realm.

4. Redeploy your project.

       For more information, see deploying a Director project in the Core Development Guide.

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

To specify your writable realm as the primary realm:

1. In Workbench, open config.xml for the Directory subsystem.

2. Click Add.

3. Enter this key/value pair:

   • Key: DirectoryService/realms/primary

   • Value: DirectoryService/realms/writable

4. Open your project's Directory services subsystem descriptor:

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

   

5. Click Add.

6. Enter the requested 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
   Namespacing	false
   Description	Any string

7. Redeploy your project.

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

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.

To configure a custom realm:

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

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

2. Click Add.

3. 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	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, set this value to 1. Otherwise, set it to 0 (for multiple instances).
   Startup	If you want the class instantiated on server startup, select automatic. Otherwise select manual.
   Namespacing
   Description	Any string.

   :

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

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

5. 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

6. 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

7. Redeploy your project.

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

Editing or changing realms

You can edit the current realm configurations or change realms and redeploy your project in Workbench.

To edit or change a realm configuration:

1. With your Director project open in Workbench, choose Project>Director Project>Configuration.

   

2. To edit or change a realm configuration choose the Directory tab at the top of the form:

   • To choose a new realm, select it from the dropdown list.

   • To configure or reconfigure an LDAP realm, select the Directory LDAP Options tab and enter your changes on the form.

       See LDAP directory configuration properties.

3. To edit the User subsystem LDAP options, select the User tab at the top of the form and enter your changes on the form.

       See LDAP user configuration properties.

4. Redeploy your project.

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

	User Management Guide

Copyright © 2000, 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.