i-Planet Administration Guide

Writing A Pluggable Authentication Module

This section is a task-oriented guide to writing a pluggable authentication module. It takes you through the steps for writing a pluggable authentication module. At the end of this section is a sample. You must first decide what your authentication mechanism is going to be and how many pages it will be and what inputs that the user will have to enter for each page.

Writing the Module

You must first write a stand-alone Java class that will call your specific authentication process, library, or the interface that it requires. In many cases, this will require the Java Native Interface (JNI) to have access to C or C++ library or system call.

You will most likely save time if you get it working in a stand-alone environment before you integrate it into i-Planet.

To Write a Pluggable Authentication Module

Write a stand-alone Java class that will call your specific authentication process, library, or the interface that it requires.

Test your module in a stand-alone environment.

Integrating the Module

Assume you have a Java class called com.companyx.auth.MyLogin that takes two inputs on the command line from a user. One input is a userId and the second is a password. MyLogin then passes these two inputs to two routines called myAuthenticateId(Id) and myAuthenticatePass(pass), which in turn calls the authentication-specific library and returns a success or fail with an error message if it fails.

After you have written your pluggable authentication module and tested it, you must integrate it into i-Planet. Use the following procedure to integrate your module into i-Planet.

To Integrate Your Pluggable Authentication Module

Modify your class to do the following:
import com.sun.authd.* extend com.sun.authd.Login implement the validate(), init(), and getUserTokenId() methods
The validate method replaces your input gathering method. Each time the user submits an HTML page, the validate() method will be called. In the method, you call your authentication-specific routines. At any point in this method, if the authentication has failed, you must throw a LoginException. If desired, you can pass the reason for failure as an argument to the exception. This reason will be logged in the i-Planet authentication log.

init() should be used if your class has any specific initialization such as loading a JNI library. init() is called once for each instance of your class. Every authentication session creates a new instance of your 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 i-Planet authentication server. This is the string the authenticated user will be known as in the i-Planet server. A login session is deemed successful when all pages in the MyLogin.properties file have been sent and your module has not thrown an exception.

Create a MyLogin.properties file.

This file contains some simple directives which tell the i-Planet authentication daemon how to create the HTML pages for your login class dynamically. Since MyLogin requires two screens with one input each, the MyLogin.properties file will look like the following:
SCREEN TEXT Welcome to my login pages TIMEOUT 60 TOKEN Please enter your company ID SCREEN TIMEOUT 120 TEXT Welcome to my second page PASSWORD Please enter your password
This .properties file tells the i-Planet authentication daemon to send two successive pages to the user. After each submit, your MyLogin validate routine will be called with the inputs made available through public getXX methods of the Login class.

Compile your java class.

Include /opt/SUNWjeev/classes/authd.jar and /opt/SUNWjeev/classes/acm.jar in your CLASSPATH.

Note -
If you use a package name to create the directories for the package, note the name that you used.

Copy your class file to /opt/SUNWjeev/classes.

Note -
If you use a jar file, you will need to edit the /opt/SUNWjeev/bin/iplsrv script and add your jar file to the web server's CLASSPATH. You can also just add it to your root CLASSPATH. The iplanet_srv script will pick it up.

If you have JNI library, you must copy it into /opt/SUNWjeev/lib/sparc, or you will need to modify the LD_LIBRARY_PATH of iplsrv script.

Copy your MyLogin.properties file to /etc/opt/SUNWstnr.

Add your full package.class name to the authenticators property in the platform.conf file.
```
   authenticators=com.sun.login.unix.Unix
com.companyx.auth.MyLogin
```

Add the lines to the /opt/SUNWsnrp/policy/reverseproxy.policy file on the i-Planet gateway.

http://host:port/login/MyLogin

https://host/login/MyLogin

Be sure to add both http and https.

Restart the web server on the i-Planet server.

Restart the reverse proxy server on the i-Planet gateway.

Test your login.

The java file for `MyLogin` Module

Missing Cross Reference Target contains a sample Java file for MyLogin Module.

package com.companyx.auth;

import com.sun.authd.*;

public class MyLogin extends Login {

	private String userTokenId;

	public MyLogin() throws LoginException{}

	public void init() throws LoginException {}

	public void validate() throws LoginException {

			String token = getToken();
			if (getCurrentState() == 1) {
				int ret = myAuthenticateId(token);
				if (ret == 0) {
						throw new LoginException("Invalid UserId: " + userTokenId);
		 		}
			}

			else {
		 	 	int ret = myAuthenticatePassword(token);
		 		if (ret == 0) {
						throw new LoginException("Invalid Password: " + userTokenId);
		   		}
		 		userTokenId = token;
			}

	}

	public String getUserTokenId() {
			return userTokenId;
	}

	public int myAuthenticateID(
			Sting userID
	)
	{
			return 1;
	}
	public int myAuthenticatePassword(
			String userId
	)
	{
			return 1;
	}

}

There is also a sample in /opt/SUNWstnr/sample/auth/com/sun/login that uses most of the methods in the Login class. There is also a javadoc in /opt/SUNWstnr/docs/javadocs/com/sun/authd for the Login class.