Sun OpenSSO Enterprise 8.0 Integration Guide

Configuring First-Time User Login Behavior

When a user logs into the protected application through OpenSSO Enterprise for the first time, after being provisioned, the user should be prompted to set his challenge/response answers. These answers can later be used to verify the user's identity when the user wants to reset a forgotten password.

To configure this first-time user login behavior, complete the following steps:

The following figures illustrate the process flow for this first-time user login behavior.

Figure 1–6 Process Flow for First-Time User Login

Text-based. No further explanation necessary.

Figure 1–7 Process Flow for First-Time User Login (continued)

To Configure OpenSSO Enterprise First-Time User Login Behavior

Develop a custom post-authentication plug-in.

You can write your own custom post authorization plug-in, or you can use the sample source code that comes with OpenSSO Enterprise. See Developing a Post-Authentication Plug-In for First-Time User Login for more information.

Compile the post-authentication plug-in code.

See To Compile the Post-Authentication Plug-In Code for detailed information.

Use the OpenSSO Enterprise console to modify first-time user login settings.
1. Log in to the OpenSSO Enterprise administration console.
2. Click the Access Control tab, and then navigate to RealmName> Data Stores > DataStoreName.
3. For the property LDAP User Attributes, add the LDAP attribute employeeType.
4. Click Save.
5. Click “Back to Data Stores.”
6. Click the Authentication tab.
7. Click “All Core Settings.”
8. For the property “Authentication Post Processing Classes,” add the value com.sun.identity.authentication.spi.FirstTimeLogin.
9. Click Save.
10. Click “Back to Authentication,” and then click "Back to Access Control".
11. Click the Configuration tab, and then navigate to Server & Sites > Default Server Settings > Advanced.
12. Click Add to add a new property. Example:
  
  This is an example of an LDAP attribute name. Use your own LDAP attribute name here.
  
  Property Name:
  
  com.sun.identity.firsttime_login_attr_name
  
  Property Value:
  
  employeeType
13. Click Save.
  
  The following warning message is displayed:
  
  "Server Profile was updated. Unidentified property, com.sun.identity.firsttime_login_attr_name"
  
  Ignore this warning.
14. Log out of the OpenSSO Enterprise console.

Copy your custom post-authentication plug-in classfile (example: FirstTimeLogin.class) to the following OpenSSO Enterprise web-app directory:

WEB-INF/classes/com/sun/identity/authentication/spi

Be sure to create directories that don't already exist to reflect the package. Example: /opt/SUNWappserver91/domains/opensso4idm/applications/j2ee-modules/opensso/WEB-INF/classes/com/sun/identity/authentication/spi

Restart the OpenSSO Enterprise web container for the changes to take effect.

Developing a Post-Authentication Plug-In for First-Time User Login

Your custom post-authentication plug-in, or module, must minimally perform the following operations:

Read the value of an LDAP attribute, its name to be specified in an OpenSSO Enterprise property com.sun.identity.firsttime_login_attr_name.
If the value of the attribute is true, determine that the user is logging-in for the first time.
If the user is logging in for the first time, redirect to the Identity Manager URL where the user can enter or set challenge questions.

Before you begin, determine the LDAP attribute you will use to identify a user who is logging in for the first time, and replace occurrences of employeeType in the following instructions with the custom LDAP attribute name. This attribute is ideally a boolean LDAP attribute that takes values true or false. In the procedures described below, the attribute is employeeType.

You can develop your own code based on the code sample made available in the opensso.zip distribution. Or you can use the source code that comes with OpenSSO Enterprise. Choose only one of the following procedures:

Writing Your Own Post-Authentication Plug-In

The following code sample is a post-authentication plug-in. In this code sample, OpenSSO Enteprise redirects to an Identity Manager URL if the value of the configured LDAP attribute is true.

Replace occurrences of com.sun.identity.authentication.spi.FirstTimeLogin with the fully qualified name of your class.

Example 1–1 Code Sample: Post-Authentication Plug-In for First-Time Login

package com.sun.identity.authentication.spi;

import com.iplanet.am.util.Debug;
import com.iplanet.am.util.Misc;
import com.iplanet.am.util.SystemProperties;
import com.iplanet.sso.SSOToken;
import com.iplanet.sso.SSOException;
import com.sun.identity.authentication.service.AuthUtils;
import com.sun.identity.authentication.util.ISAuthConstants;
import com.sun.identity.idm.AMIdentity;
import com.sun.identity.idm.IdRepoException;
import com.sun.identity.idm.IdUtils;
import java.io.IOException;
import java.lang.System;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;



public class FirstTimeLogin implements AMPostAuthProcessInterface {

    //add this attribute as an advance property
    private static final String FIRSTTIME_LOGIN_ATTR_NAME = 
        "com.sun.identity.firsttime_login_attr_name";  

    private static Debug debug = Debug.getInstance("FirstTimeLogin");

    /** 
     * Post processing on successful authentication.
     * @param requestParamsMap contains HttpServletRequest parameters
     * @param request HttpServlet  request
     * @param response HttpServlet response
     * @param ssoToken user's session
     * @throws AuthenticationException if there is an error while setting
     * the session paswword property
     */
    public void onLoginSuccess(Map requestParamsMap,
        HttpServletRequest request,
        HttpServletResponse response,
        SSOToken ssoToken) throws AuthenticationException {

        if (debug.messageEnabled()) {
            debug.message("FirstTimeLogin.onLoginSuccess called: 
                 Req:" + request.getRequestURL());
        }

        String strAttributeName = SystemProperties.get(FIRSTTIME_LOGIN_ATTR_NAME);

        try {

            if(strAttributeName != null && !strAttributeName.trim().equals("")){
                AMIdentity amIdentityUser = IdUtils.getIdentity(ssoToken);
                Map attrMap = amIdentityUser.getAttributes();
                String strAttributeValue = Misc.getMapAttr(
                    attrMap, strAttributeName, null);
                if (debug.messageEnabled()) {
                    debug.message("FirstTimeLogin.onLoginSuccess: 
                         " + strAttributeName + "=" + strAttributeValue);
                }
		System.out.println("FirstTimeLogin.onLoginSuccess: 
      " + strAttributeName + "=" + strAttributeValue);
             if(strAttributeValue != null && strAttributeValue.equalsIgnoreCase("true")){
                 if (request != null){
                 request.setAttribute(AMPostAuthProcessInterface.POST_PROCESS_LOGIN_SUCCESS_URL,
                           "http://localhost:8081/idm/user/main.jsp?goto=http://mail.yahoo.com");
                    }
                }				
            }

            if (debug.messageEnabled()) {
                debug.message("FirstTimeLogin.onLoginSuccess: 
                    FirstTimeLogin " + "concluded successfully");
            }
        } catch (IdRepoException ire) {
            debug.error("FirstTimeLogin.onLoginSuccess: 
                 IOException while " + "fetching user attributes: " + ire);
        } catch (SSOException sse) {
            debug.error("FirstTimeLogin.onLoginSuccess: 
                 SSOException while " + "setting session password property: " + sse);
        }
    }

    /** 
     * Post processing on failed authentication.
     * @param requestParamsMap contains HttpServletRequest parameters
     * @param req HttpServlet request
     * @param res HttpServlet response
     * @throws AuthenticationException if there is an error
     */
    public void onLoginFailure(Map requestParamsMap,
        HttpServletRequest req,
        HttpServletResponse res) throws AuthenticationException {
            debug.message("FirstTimeLogin.onLoginFailure: called");
    }

    /** 
     * Post processing on Logout.
     * @param req HttpServlet request
     * @param res HttpServlet response
     * @param ssoToken user's session
     * @throws AuthenticationException if there is an error
     */
    public void onLogout(HttpServletRequest req,
        HttpServletResponse res,
        SSOToken ssoToken) throws AuthenticationException {
            debug.message("FirstTimeLogin.onLogout called");
    }
}

If you want to preserve the value of the OpenSSO Enterprise goto URL, and pass it on to Identity Manager, you can do that in the post-authentication plug-in. You can retrieve the original URL parameters from the HTTP request, and incorporate them into the request to the Identity Manager URL. See the Adding Authentication Post Processing Features in Sun OpenSSO Enterprise 8.0 Developer’s Guide

Using the Post-Authentication Plug-In Sample Source Code

The sample source code is contained in file opensso/integrations/idm/src/com/sun/identity/authentication/spi/FirstTimeLogin.java. Replace occurrences of com.sun.identity.authentication.spi.FirstTimeLogin with the fully qualified name of your class. Replace the Identity Manager URL an appropriate URL to suit your deployment.

To Compile the Post-Authentication Plug-In Code

Download the Java EE SDK if you don't have it already through NetBeans or GlassFish.

From this SDK, you will need the Java servlet API classes ( available in javaee.jar ) to compile the post-authentication module source code.

Set the Java home directory.

# export JAVA_HOME=/export/software/jdk1.6.0_14
# export PATH=$JAVA_HOME/bin:$PATH

Set the Java classpath.

The following has been broken into multiple lines for readability purposes.

# export CLASSPATH=/opt/SUNWappserver91/lib/javaee.jar:
/opt/SUNWappserver91/domains/opensso4idm/applications/
  j2ee-modules/opensso/WEB-INF/lib/amserver.jar:
/opt/SUNWappserver91/domains/opensso4idm/applications/
  j2ee-modules/opensso/WEB-INF/lib/opensso-sharedlib.jar

The jar files used in this example are:

javaee.jar

Available in the Java EE SDK or in your GlassFish / NetBeans installation.
amserver.jar

Available in the opensso.war.
opensso-sharedlib.jar

Available in the opensso.war.

Compile the source file.
# javac FirstTimeLogin.java
The class file FirstTimeLogin.class is created in the current directory.