Chapter 6   Pluggable Authentication API




Pluggable Authentication API Overview

---

This chapter describes requirements for writing a supplemental authentication module to plug into iPlanet Portal Server and provides information about customizing the authentication pages.

Table 6-1 Tasks to Customize Authentication

If you want to	Do
Change login prompts	Edit the .properties file associated with the login screen that will be changed. See Understanding the .properties File.
Add authentication capability	Create .properties file for the authentication module. See Understanding the .properties File. Write and integrate an auth module.Writing a Pluggable Authentication Module.
Selectively enable or disable auth modules	Refer to iPlanet Portal Server 3.0 Administration Guide
Customize prompts and appearance for specific Domains	Refer to iPlanet Portal Server 3.0 Administration Guide.

The authentication methods available in iPlanet Portal Server include the following:

• RADIUS
  • RADUIS

  • RADIUS-to-ACE/Server

  • RADIUS-to-SafeWord

• RSA Security, Inc., Security Dynamics
  • SecurID, ACE/Server, ACE/Agent, Security Dynamics

• Secure Computing, Inc.
  • SafeWord server and tokens

• S/Key

• UNIX/NIS

• NT

• LDAP

• Personal Digital Certificate

• Membership

  
  

  ---

  Tip	Before beginning to write authentication modules, contact the e-Commerce Solutions sales representative to find out if the module needed has already been written and is available from internal resources.

  ---

  
  

For additional authentication capabilities, use the information in this chapter to write a custom authentication module and integrate it into the Portal Server.

Authentication Process Overview

---

Custom iPlanet Portal Server authentication modules require two main components:

• The .class file to authenticate the user

• The .properties file to specify prompts the user will see and the information that will be passed to the authentication module

The .class file implements the authentication type that is added. Write the authentication module to override certain methods provided by the API.

For information about the methods the module must override, see Requirements.

Understanding the .properties File

---

The .properties file is the configuration file for an authentication module. The file specifies the text, tokens, and password prompts for the login pages associated with the authentication module.

Name the authentication module's .properties file name with the base class name (no package name) and the extension .properties.

For example: Sample.properties.

This file must reside in /etc/opt/SUNWips/auth/default on the iPlanet Portal Server software.

Code Example 6-1 The Form for the Properties File

SCREEN TIMEOUT 60 TEXT Sample Login Page TOKEN Enter User Name: PASSWORD Enter User Password: SCREEN TIMEOUT 30 TEXT Sample Login Page 2 TOKEN Enter Favorite Color TOKEN Enter Secret Pin Number PASSWORD Enter Challenge form

Table 6-2 discusses the directives that can be included in a .properties file.

Table 6-2 The .properties File Directives 

Directive	Description
SCREEN	Each SCREEN entry corresponds to one authentication state (authentication HTML page). The authentication module can set which screen is next, or it can allow the iPlanet Portal Server's auth servlet progress through the screens sequentially.
TIMEOUT n	The TIMEOUT directive is used to ensure that users respond in a timely manner. If the time between when the page is sent and the user submits his response is greater than "n" seconds, a time-out page is sent.
TEXT	The TEXT directive is similar to a title for the page, and the text <xxx> appears at the top of the screen area provided for the auth module. Only one TEXT directive per SCREEN should be specified. If more than one is provided, then the last one is displayed.
TOKEN yyy	The TOKEN directive equates to the following HTML: <P><STRONG>yyy</STRONG><BR><INPUT TYPE="TEXT" NAME=TOKEN0> The input field's name starts at TOKEN0 and increments with each TOKEN or PASSWORD directive specified per SCREEN.
PASSWORD zzz	The PASSWORD directive equates to the following HTML: <P><STRONG>yyy</STRONG><BR><INPUT TYPE="PASSWORD" NAME=TOKEN0> The input field's name starts at TOKEN0 and increments with each PASSWORD or TOKEN directive specified per SCREEN.
IMAGE image-path	The IMAGE directive allows auth module writers to display a background image on each page.
<REPLACE>	The REPLACE tag allows a module to substitute dynamic text for the text accompanying token and password descriptions. Used in conjunction with the setReplaceText() method.

The specific directives included will depend on the requirements of the authentication method and the extent of customizing the appearance of the prompts and displays through the authentication process.

Each SCREEN entry corresponds to one authentication state or authentication HTML page. When an authentication session is invoked, one HTML page is sent for each state. In Table 6-2 on page 60, the first state sends an HTML page asking the users to enter a token and a password. When the users submit the token and the password, the validate() method is called. The module gets the tokens, validates them, and returns them. The second page is then sent and the validate() method is again called.

If the module throws a LoginException, an authentication failed page is sent to the user. If no exception is thrown, which implies successful completion, the users are redirected to their default page. The TIMEOUT directive is used to ensure that the users respond in a timely manner. If the time between sending the page and the response is greater than the TIMEOUT value, a time-out page is sent.

When multiple pages are sent to the user, the tokens from a previous page may be retrieved by using the getTokenForState methods. Each page is referred to as a state. The underlying authentication module keeps the tokens from the previous states until the authentication is completed.

Each authentication session creates a new instance of the authentication Java class. The reference to the class is released once the authentication session has either succeeded or failed.

---

Note	Any static data or reference to any static data in the authentication module must be thread safe.

---

Writing a Pluggable Authentication Module

---

The following sections discuss the requirements and recommendations to follow when writing a new authentication module.

Requirements

A pluggable authentication module for iPlanet Portal Server desktop must override certain methods and should adhere to specific naming conventions and standards for easy integration.

---

Note	For a list and description of the methods used to write the authentication module, see the JavaDocs at http://yourserver:port/docs/en_US/javadocs

---

• Extend com.iplanet.portalserver.auth.server.Login

• Override the validate(), init(), and getUserTokenId() methods

The validate method replaces the input gathering method. Each time the user submits an HTML page, the validate() method will be called. In the method, authentication-specific routines are called. At any point in this method, if the authentication has failed, the module must throw a LoginException. If desired, the reason for failure can be an argument to the exception. This reason will be logged in the iPlanet Portal Server authentication log.

init() should be used if the class has any specific initialization such as loading a JNI library.
init() is called once for each instance of the class. Every authentication session creates a new instance of the class. Once a login session is completed the reference to the class is released.

getUserTokenId() is called once at the end of a successful authentication session by the iPlanet Portal Server authentication server. This is the string the authenticated user will be known as in the iPlanet Portal Server environment. A login session is deemed successful when all pages in the .properties file have been sent and the module has not thrown an exception.

Recommendations

• Add /opt/SUNWips/classes to the CLASSPATH environment variable

• Naming the authentication module in the following way allows (and forces) the module's class file to be installed with the other auth modules provided with the iPlanet Portal Server software
  com.iplanet.portalserver.service.auth.module.sample

About using helpers

A helper is a process that runs separately from the Portal Server but processes the server's authentication requests associated with a given authentication module. In the case of the Portal Server, a helper is a C-language process.

The helper listens for requests on a socket. If data is passed in the clear over the connection, the helper should only accept requests originating from the localhost. The helper can be started at boot time. The startup script is in:

/etc/rc3.d/S42ipsserver

Some authentication SDKs are supplied as C-language libraries that must be statically linked. If using JNI is undesirable for portability, design, or performance reasons, using an authentication helper is an option.

The UNIX, SafeWord, SecurID, and RADIUS authentication modules employ helpers.

Integrating the Module

After the pluggable authentication module has been written and tested, it must be integrated into the iPlanet Portal Server software with the following procedure.

1. Create a directory for the authentication module under:

   /opt/SUNWips/lib/

2. Put the authentication .class file into the directory created for it.

3. Put the corresponding .properties file in:

   /etc/opt/SUNWips/auth/default

4. Create an XML file to update the iwtAuth component of the Portal Server or domain. See Table 6-4 on page 67 for an example of the XML file.
   1. Make a copy of /etc/opt/SUNWips/xml/iwtAuth.xml

      For example, /etc/opt/SUNWips/xml/iwtAuth.xml.update

   2. Add the values for your module to the new XML file.

   Use the example XML file provided in Code Example 6-4.

   
   

   ---

   Note	The new XML file includes only the attributes to be updated. The component name part is omitted.

   ---

   
   

   1. Import the XML file.

      # /opt/SUNWips/bin/ipsadmin change component iwtAuth <iwtAuth.xml.update>

5. Restart the iPlanet Portal Server.

   # /opt/SUNWips/bin/ipsserver start

Sample Code

The following samples show the form and content of the files associated with an authentication module:

• Sample Properties File

• Sample Login Module Source

• Sample XML File

Sample Properties File

The following sample file Sample.properties can be located in:

/opt/SUNWips/sample/auth/module

where /opt is the directory in which it is installed by default.

Code Example 6-2 Sample.properties File

---

TEXT This is a sample login page

TOKEN First Name

Sample Login Module Source

The following sample is in a file named Sample.java located in:

/opt/SUNWips/sample/auth/module/sample

where /opt is the directory in which it is installed by default.

Code Example 6-3 Sample Java Module—Sample.java 

---

package com.iplanet.portalserver.sample.auth_modules;

import java.util.*;

import com.iplanet.portalserver.auth.server.*;

public class Sample extends Login {

private String userTokenId;

private String firstName;

private String lastName;

public Sample() throws LoginException{

System.out.println("Sample()");

}

public void init() throws LoginException {

System.out.println("Sample initialization");

}

public void validate() throws LoginException {

int currentState = getCurrentState();

if (currentState == 1) {

firstName = getToken(1);

lastName = getToken(2);

if (firstName.equals("") || lastName.equals("")) {

throw new LoginException("names must not be empty");

}

return;

}

else if (currentState == 2) {

String pass = getToken(1);

System.out.println("Replace TExt first: " + firstName + " last: " + lastName);

setReplaceText(1, firstName);

setReplaceText(2, lastName);

return;

}

else if (currentState == 3) {

String[] tokens = getAllTokens();

for (int i=0; i<getNumberOfTokens(); i++) {

System.out.println("Token-> " + tokens[i]);

}

return;

}

else if (currentState == 4) {

String[] tokens = getAllTokensForState(1);

for (int i=0; i<getNumberOfTokensForState(1); i++) {

System.out.println("Token-> " + tokens[i]);

}

}

userTokenId = firstName;

}

public String getUserTokenId() {

return userTokenId;

}

}

Sample XML File

The following is a sample XML file. The values in bold type represent the updates made to the XML file. Replace the values in bold type with the values for the new authentication module.

Code Example 6-4 Sample XML File—ispAuth.xml.update 

---

<iwt:Att name="iwtAuth-authMenu"

desc="Authentication Menu"

type="multichoice"

idx="a1"

userConfigurable="TRUE">

<Val>Radius</Val>

<Val>SecurID</Val>

<Val>SafeWord</Val>

<Val>SKey</Val>

<Val>Unix</Val>

<Val>Ldap</Val>

<Val>NT</Val>

<Val>Sample</Val>

<Rperm>ADMIN</Rperm><Rperm>OWNER</Rperm>

<Wperm>ADMIN</Wperm>

<CVal>Radius</CVal>

<CVal>SecurID</CVal>

<CVal>SafeWord</CVal>

<CVal>SKey</CVal>

<CVal>Unix</CVal>

<CVal>Ldap</CVal>

<CVal>NT</CVal>

<CVal>Sample</CVal>

</iwt:Att>

<iwt:Att name="iwtAuth-adminAuthModule"

desc="Admin Authenticator"

type="singlechoice"

idx="a4"

userConfigurable="TRUE">

<Val>Unix</Val>

<CVal>Radius</CVal>

<CVal>Simple</CVal>

<CVal>SecurID</CVal>

<CVal>SafeWord</CVal>

<CVal>SKey</CVal>

<CVal>Unix</CVal>

<CVal>Ldap</CVal>

<CVal>NT</CVal>

<CVal>Sample</CVal>

<Rperm>ADMIN</Rperm>

<Wperm>ADMIN</Wperm>

</iwt:Att>

<iwt:Att name="iwtAuth-authenticators"

desc="Authentication Modules"

type="multichoice"

idx=""

userConfigurable="TRUE">

<Val>com.iplanet.portalserver.auth.module.radius.          Radius</Val>

<Val>com.iplanet.portalserver.auth.module.securid.          SecurID</Val>

<Val>com.iplanet.portalserver.auth.module.safeword.          SafeWord</Val>

<Val>com.iplanet.portalserver.auth.module.skey.SKey          </Val>

<Val>com.iplanet.portalserver.auth.module.unix.Unix          </Val>

<Val>com.iplanet.portalserver.auth.module.ldap.Ldap          </Val>

<Val>com.iplanet.portalserver.auth.module.cert.Cert          </Val>

<Val>com.iplanet.portalserver.auth.module.nt.NT          </Val>

<Val>com.iplanet.portalserver.auth.module.          application.Application</Val>

<Val>com.iplanet.portalserver.auth.module.sample.          Sample</Val>

<Rperm>ADMIN</Rperm><Rperm>OWNER</Rperm>

<Wperm>ADMIN</Wperm>

<CVal>com.iplanet.portalserver.auth.module.radius.          Radius</CVal>

<CVal>com.iplanet.portalserver.auth.module.securid.          SecurID</CVal>

<CVal>com.iplanet.portalserver.auth.module.          safeword.SafeWord</CVal>

<CVal>com.iplanet.portalserver.auth.module.skey.          SKey</CVal>

<CVal>com.iplanet.portalserver.auth.module.unix.          Unix</CVal>

<CVal>com.iplanet.portalserver.auth.module.ldap.          Ldap</CVal>

<CVal>com.iplanet.portalserver.auth.module.cert.          Cert</CVal>

<CVal>com.iplanet.portalserver.auth.module.nt.NT          </CVal>

<CVal>com.iplanet.portalserver.auth.module.          application.Application</CVal>

<CVal>com.iplanet.portalserver.auth.module.          sample.Sample</CVal>

</iwt:Att>