Programming Guides › Programming Guide for Java › Custom Authentication Schemes › How To Customize CA IdentityMinder Authentication › Implement the AuthenticationModule Interface

Implement the AuthenticationModule Interface

Write a custom authentication module that extends com.netegrity.webapp.authentication.AuthenticationModule, as follows:

package com.netegrity.webapp.authentication;

/**
 * Implement this interface to write a pluggable authentication module for use with the Framework Native auth.
 * The implemented class typically goes hand in hand with a login.jsp/html page that collects some information. 
 * This information is passed along to the AuthenticationModule for processing. Typical information captured can include
 * userid and password. 
**/
public abstract class AuthenticationModule 
{
	/**
	 * The httpSession attribute name where the exception from the authenticate method will be available.
	 */
	public static final String FWAUTH_EXCEPTION = "IAMFW_LOGIN_EXCEPTION";
	public static Vector MANDATORY_USER_ATTRIBS = null;
	public static Log _log = null;
	
	static 
	{
    	_log = LogFactory.createLog("im.AuthenticationModule");
    	
    	MANDATORY_USER_ATTRIBS = new Vector();
    	//mandatory attribs for a user object
    	MANDATORY_USER_ATTRIBS.add(User.PROPERTY_ENABLED_STATE);
    	MANDATORY_USER_ATTRIBS.add(User.PROPERTY_FRIENDLY_NAME);
	}

	public AuthenticationModule()
	{
	}
	
	/**
	 * This method will be called first by the FrameworkLoginFilter. With the given set of information
	 * in the login.jsp/html, the AuthenticationModule should be able to find a User in the given ImsDirectory.
	 * 
	 * @param request - The request object
	 * @param response - The response object 
	 * @param env - The environment being accessed.
	 * @return The user as found in the provided ImsDirectory. 
	 * @throws Exception - This exception will be put in the httpSession
        * as an attribute by the name FWAUTH_EXCEPTION 
	 */
	public abstract User disambiguateUser(HttpServletRequest request, HttpServletResponse response, ImsEnvironment env) throws Exception;
	
	/**
	 * @param request - The request object
	 * @param response - The response object 
	 * @param env - The environment being accessed.
	 * @return The user as found in the provided ImsDirectory. 
	 * @throws Exception - This exception will be put in the httpSession 
        * as an attribute by the name FWAUTH_EXCEPTION 
	 */
	public abstract boolean authenticate(HttpServletRequest request, HttpServletResponse response, ImsEnvironment env, User user) throws FwAuthenticationException;
}

The default authentication module is listed here for reference. You can write your own authentication module using the default as a model. In general, you must be able to find and return a valid user in the directory of the CA IdentityMinder environment being protected using the form and header variables.

Note: A sample authentication module, which you can also use as a model, is available in the following location:

admin_tools/samples/AuthenticationModule

package com.netegrity.webapp.authentication;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.netegrity.llsdk6.imsapi.exception.FwAuthenticationException;
import com.netegrity.llsdk6.imsapi.exception.NoSuchObjectException;
import com.netegrity.llsdk6.imsapi.managedobject.User;

import com.netegrity.llsdk6.imsapi.ImsDirectory;
import com.netegrity.llsdk6.imsapi.ImsEnvironment;
import com.netegrity.sdk.apiutil.SmApiException;

/**
 * The default Framework Authentication module. This works in conjunction 
 * to the default login.jsp page. The Attribute to be used for looking up
 * the user is %USER_ID%.
 *
 */
public class DefaultAuthenticationModule extends AuthenticationModule {
	public static final String FORM_VAR_USERNAME="username";
	public static final String FORM_VAR_PASSWORD="password";
	
	public User disambiguateUser(HttpServletRequest request, HttpServletResponse response, ImsEnvironment env) throws Exception
	{
		String username = request.getParameter(FORM_VAR_USERNAME);
		
		User user = null;
		try
		{
			ImsDirectory dir = env.getImsDirectory();
			user = dir.getUserProvider().disambiguateUser(username, MANDATORY_USER_ATTRIBS.elements());
		}
		catch (NoSuchObjectException nsoe)
		{
			throw new FwAuthenticationException("Username and password do not match.");
		}
		return user;
	}
	public boolean authenticate(HttpServletRequest request, HttpServletResponse response, ImsEnvironment env, User user) throws FwAuthenticationException
	{
		String password=request.getParameter(FORM_VAR_PASSWORD);
		//verify the user against the directory.
		
		boolean authenticated= false;
		try
		{
			authenticated = user.authenticate(password);
		}
		catch (SmApiException e) 
		{
			_log.logDebug("Exception while authenticating: "+e.getMessage());
			_log.logDebug(e);
			throw new FwAuthenticationException(e.getMessage());
		}
		if (!authenticated)
		{
			throw new FwAuthenticationException("Username and password do not match.");
		}
		return authenticated;
	}
}

Save your compiled Java class file to the iam_im.ear\custom folder.