How do I customize CA Identity Manager Authentication?

Document ID : KB000053584
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

When not using CA SiteMinder, CA Identity Manager provides its own user authentication. You can customize this authentication scheme by adhering to the following process:

  • Modify the JSP-based login page credential form to suit your authentication requirements.
  • Write a module in Java that extends the AuthenticationModule interface so that it implements your changes to the login page.
  • Configure the Java class name and the login page name through the Management Console.

Solution:

How To Customize CA Identity Manager Authentication

When not using CA SiteMinder, CA Identity Manager provides its own user authentication. You can customize this authentication scheme by adhering to the following process:

  • Modify the JSP-based login page credential form to suit your authentication requirements.
  • Write a module in Java that extends the AuthenticationModule interface so that it implements your changes to the login page.
  • Configure the Java class name and the login page name through the Management Console.

Modify the Login Credential Form

By default, the CA Identity Manager authentication scheme accepts the user name and password at login, provided in a credential form in the login.jsp file. These parameters are tested against credentials in the directory configured for the protected environment.

You can modify login.jsp to suit your authentication requirements. A partial listing login.jsp is shown following.

. 
<form NAME="Login" METHOD="POST" target="_top"> 
. . 
User Name: <input type="text" name="username" /> 
Password:<input type="password" name="password" /> 
. .
</form>
. .

To modify the credential form

  • Edit login.jsp (located in IdentityMinder.ear\user_console.war) as your authentication requirements demand.
    For example, you might substitute social security number for user name as follows:
    Social Security Number: <input type="text" name="socsecnum" />
  • Save the changes to a different file name in case at some time you want to return to the default authentication scheme. Remember that the default login.jsp will get overwritten when you apply an upgrade.

The login page is ready for your environment.

Implement the AuthenticationModule Interface

You must write a custom authentication module that extends com.netegrity.webapp.authentication.AuthenticationModule, listed following.

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 will go 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 using the default as a model. In general, you must be able to find and return a valid user in the directory of the Identity Manager Environment being protected using the form and header variables.

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 will work 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\user_console.war\WEB-INF\lib folder.

Configure the Java Class and Login Page

The login form file and the authentication module are specified for an environment using the Management Console.

To configure the authentication provider class and the login page

  • In the Management Console navigate to the Advanced Settings, User Console pane for the particular environment.
  • Enter the fully-qualified Class name of the compiled Java module in the Framework Native Login Properties group box.
  • Enter the name of the login page in the same group box.
  • Click Save.

The custom authentication scheme is configured.