Previous Page: Managing Appliance Certificates  Next Page: Custom Login Pages

User Management Servlets

iChain User Services is a collection of four Java* servlets that provide a lightweight and easy-to-manage user self-provisioning environment that is based on open standards (LDAP). No Novell client is needed. The user self-provisioning services include:

Java Servlets

The services in iChain User Services are provided by the following four Java servlets:

These servlets can be found on the Authorization Services CD under the \servlets directory. This directory contains both a compiled file (.class) and the source file (.java) for each servlet.

Servlet Requirements

The following components are required for using iChain User Services:


This servlet enables Web-based user self-registration, as shown in Figure 30 and Figure 31.

Figure 30
Web-Based User Self-Registration

Figure 31
User Self-Registration Results


This servlet enables Web-based user account modification, as shown in Figure 32 and Figure 33:

Figure 32
Web-Based User Account Modification

Figure 33
User Account Modification Results


This servlet enables users to change their own passwords, as shown in Figure 34:

Figure 34
Password Change


This servlet enables a Password Manager that will give users a way of changing their passwords after their passwords expire, while they still have grace logins remaining. The Password Manager will check (and display to the user) the number of grace logins remaining and will provide an automatic destination redirection once a password has been successfully changed. See Figure 35.

Figure 35
Password Manager

If the grace logins are greater than 1, the user will have the option to bypass the password change screen. If the grace login equals 1, the user will be forced to change his or her password before continuing on. See Figure 36.

Figure 36
Password Grace Logins

To set up the iChainPasswordMgr servlet:

  1. From the proxy server Web administration GUI, select Configure > Access Control tab.

  2. Enter the servlet information in the Password Management Servlet URL field.

  3. Use the full http URL (for example,

Servlet Configuration File

The servlets use a configuration file that they read upon initialization to customize their functionality to your environment and to easily provide localization (or modification) of all message and error strings. This configuration file also allows you to make any LDAP directory attributes available to the user for user account creation or modification. The name of this required configuration file is ICHAINAPPCONFIG.TXT.

NOTE:  The servlets expect the ICHAINAPPCONFIG.TXT file to reside in the same directory as the servlets themselves (where you place the *.class servlet files).

The settings that can be modified/customized via this configuration are:

The following is an example of the format and syntax of how to make the LDAP attributes of "title" (Job Title) and "mail" (E-mail Address) available to the user during account creation or modification:

---------- ---------- ---------- ---------- ----------

# ATTRIBUTES for User Creation or Modification                    # Format: <LDAP name>, <"HTML display">, <Required: yes/no>   # Example: givenName, "First Name", yes                             # NOTE: "cn", "givenName," "surname", & "UserPassword" are    #         automatically provided and required by default                #        (do NOT list these 4 attributes in this file)               NumberOfAttributes=2                                       attrl=title, "JobTitle", no                                         attr2=mail, "Email Address", yes

---------- ---------- ---------- ---------- ----------

The attributes can also be designed as "required" or "not required" when they are presented to the user during account creation or modification.

Auxiliary Class Support

The ICHAINAPPCONFIG.TXT configuration file does support auxiliary class attributes. If the attributes that you want to list in the above attributes section are attributes in an auxiliary class, you will need to add an extra entry at the end of the attrX line as shown in the following example:

attr3=commerceAccountID, "Commerce ID", no, commerceAcct

In this example, commerceAccountID is the LDAP attribute name and commerceAcct is the auxiliary class that this attribute is a member of.

Servlet Installation and Setup


There are seven files that need to be placed in the proper locations for the iChain User Services to work correctly:

  1. Place the four servlets (iChainAddUser.class, iChainModifyUser.class, iChainPasswordChange.class, and iChainPasswordMgr.class) in the servlet directory of your servlet engine.

  2. Place the iChainAddUser$ISOPasswordTemplate.class class file in the same directory as the servlets (the servlet directory of your servlet engine).

  3. Place the ICHAINAPPCONFIG.TXT configuration file in the same directory where you placed the servlets.

  4. Place the TOP.GIF image file at the root documents directory of your Web server. (For example: for IIS, place the image file in C:\INETPUB\WWWROOT. For Netscape/Novonyx, place the image file in NOVONYX\SUITESPOT\DOCS.)


To set up the iChain User Services, modify the iChainAppConfig.txt configuration file to match your environment. Make sure this configuration file resides in the same file system directory as the servlets.

In order for the servlets to get the user identity and credential information (via the Authorization section of the HTTP header), you must enable the Forward Authentication Information to Web Server authentication option on the iChain Proxy Server for the Web server running these servlets at Configuration > Web Server Accelerator > Modify > Authentication Options.

The servlets in the iChain User Services are optimized for use with iChain 2.1. This means that the work of user authentication is offloaded to the iChain Proxy Server rather than having the servlets themselves perform user authentication. Of the four servlets, iChainAddUser is designed to be configured as an iChain public resource, while the other three servlets (iChainModifyUser, iChainPasswordChange, and iChainPasswordMgr) are designed to be configured as private (restricted or secure) resources.

The three restricted or secure iChain servlets extract the user's identity from the base64-encoded Authorization section of the HTTP header (which is populated by the iChain Proxy Server after the user authenticates).

IMPORTANT:  Make sure that the directory path where these *.class files reside on your server are in the runtime CLASSPATH of your servlet engine's JVM. If they are not, the servlets will fail upon initialization because of the getClass().getResourceAsStream(configFileName) method call that they make when attempting to read the configuration text file (that should be in the same directory as the servlet *.class files) when the servlets initialize.

Configuring iChainAddUser As a Public Resource

To configure the iChainAddUser servlet as a Public resource while also configuring the other servlets in the same directory as Restricted resources, you will need two Protected Resource entries on the ISO object.

For example, on the ISO object's Protected Resource tab, enter the following:

URL Prefix Access



This makes the iChainAddUser servlet a Public resource, and all other servlets in that directory are restricted (login/authentication is required before access is given).

Enabling a Password Dictionary

To enable support for a Password Dictionary file (which lists passwords that users are not allowed to use):

  1. Select the ISO object > Password Policy tab.

  2. Select the Check Password Dictionary check box.

  3. In the Password Dictionary File field, list the full HTTP URL where the Dictionary file resides. For example,

The Dictionary file must be a text file, and each word must be on its own line. For example, the contents of your text file might look like the following:


OS/Servlet Engine Environments

The iChain User Services servlets require LDAP class support that is commonly provided by an LDAP.JAR file. You can get the latest copy of this required LDAP.JAR file from Novell's Java LDAP NDK, titled "LDAP Classes for Java". This kit is available on the Novell Developer Web site.

For convenience, Novell has included this file (renamed to LDAP-NOVELL.JAR) on the iChain Authorization Server CD, in the \SERVLETS directory. You can use this LDAP-NOVELL.JAR file without having to install any additional library kit. Simply configure your servlet engine to recognize the LDAP-NOVELL.JAR file, typically by either adding this file to your server's CLASSPATH or by coping it to your servlet engine's \LIB directory.

NOTE:  The LDAP-NOVELL.JAR file does NOT have to be renamed to LDAP.JAR to be used (filenames do not matter in this case).

Because there are many different OS and servlet engine environments, it would be virtually impossible to document the installation for every environment. Here are a few examples:

NetWare 5.1 Server with Novell Servlet Gateway and NetWare Enterpriser Web Server

In this example, the Novell Servlet Gateway is previously installed. See the Novell Developer site to download this gateway.

  1. Verify the functionality of the Novell Servlet Gateway by running a servlet such as SnoopServlet.

  2. Verify the server has the current support pack.

  3. Check the version of java.nlm at the Novell NDK site. If it is less than 1.22, it will need to be updated to Novell JVM for NetWare v1.X.X (1.2.2. or higher).

  4. Install the LDAP Class Libraries for Java on the NetWare server. This will place the ldap.jar file in the sys:/java/lib directory.

  5. Follow the installation instructions to add a classpath to the sys:\etc\java.cfg file:






  6. Place the four servlets (iChainAddUser.class, iChainModifyUser.class, iChainPasswordChange.class, iChainPasswordMgr.class) in the SYS:\JAVA\SERVLETS directory.

  7. Place the ICHAINAPPCONFIG.TXT configuration file in the same directory. Modify it as described in Servlet Configuration File.

  8. Place the TOP.GIF image file at the root documents directory (SYS:NOVONYX\SUITESPOT\DOCS).

NetWare 6 Server with Tomcat and Apache
  1. Verify that Tomcat is functioning properly. This can be done by accessing a servlet in the SYS:\TOMCAT\33\WEBAPPS\ROOT\WEB-INF\CLASSES directory, such as SnoopServlet.

  2. Install the LDAP Classes for Java on the NetWare server. This will place the ldap.jar file in the sys:/java/lib directory. Follow the install instructions to add a classpath to the SYS:TOMCAT\33\BIN\TOMCAT33.NCF file:

    envset TOMCAT_CLASSPATH=sys:\java\lib\


    envset TOMCAT_CLASSPATH=$TOMCAT_CLASSPATH;SYS:\java\njclv2\lib\jndi.jar

    envset TOMCAT_CLASSPATH=$TOMCAT_CLASSPATH;SYS:\java\njclv2\lib\njclv2.jar

    envset TOMCAT_CLASSPATH=$TOMCAT_CLASSPATH;SYS:\java\lib\ldap.jar

  3. Place the four servlets (iChainAddUser.class, iChainModifyUser.class, iChainPasswordChange.class, iChainPasswordMgr.class) in the SYS:\TOMCAT\33\WEBAPPS\ROOT\WEB-INF\CLASSES directory.

  4. Place the ICHAINAPPCONFIG.TXT configuration file in the same directory. Modify it as described above.

  5. Place the TOP.GIF image file at the root documents directory (SYS:\NOVONYX\SUITESPOT\DOCS).

5.1 Server with Enterprise Web Server: WebSphere 3.53 (running in servlet engine only mode)
  1. Copy servlets and .txt files to OnDemand/WAS server SYS:\WEBSPHERE\APPSERVER\SERVLETS

  2. Edit ICHAINAPPCONFIG.TXT to add proper LDAP server address, contexts, usernames, and passwords.


  4. Expand LDAP class libraries (this puts the ldap.jar file in SYS:/JAVA/LIB directory).


    envset WAS_CP=WAS_CP;$JAVA_HOME\lib\ldap.jar

  6. Access the servlets with a URL similar to http://<hostname>/servlet/iChainAddUser.

Open Source

Although the iChain User Servlets are functional and usable right out of the box, the full source code to these servlets is included for those who require more functionality or more customization than is normally provided with these core user services.

  Previous Page: Managing Appliance Certificates  Next Page: Custom Login Pages