Searching Sun Java Communications Suite

Follow Us on Twitter

This image is for Home icon. Home
Read Me First
Purpose and Policy
Contact Wiki Administrators
How to Contribute
Frequently Asked Questions
Frequently Accessed Pages
Recently Updated Pages

Cut Your Storage Costs!

Comms Suite Docs

Convergence
Messaging Server
Calendar Server 7
Indexing and Search Service
Calendar Server
Instant Messaging
Delegated Administrator
Connector for Outlook
Communications Express
Mobile Communications
Printable Docs

Release Specific Docs

Communications Suite 7 Docs
Communications Suite 6 U2 Docs
Communications Suite 6 U1 Docs
Communications Suite 6 Docs
Communications Suite 6 U2 RR Snapshot
Communications Suite 6 U1 RR Snapshot
Communications Suite Snapshot Updates
Communications Suite 6 RR Snapshot
Communications Suite 5
Java ES 2005Q4
Java ES 2005Q1
Java ES 2004Q2
Java ES 2003Q4
Sun ONE Messaging Server 6
iPlanet Messaging Server 5.2

Go Mobile!

Writing a Custom Authentication Module for Convergence

Sun Convergence server provides an interface that enables you to create custom user authentication in the form of a customizable Java-based authentication module. The custom authentication module allows an organization to use a non-Sun LDAP mechanism (for example, an RDBMS, flat-text file or third-party LDAP server) to provide authentication functionality.

Note
By default, Convergence uses Sun Java System Directory Server for authentication store. For information about administering the default authentication feature, see Authentication

Basic Concepts

This section defines the terms used in this article. In addition to this, this section also describes the authentication framework architecture and its components.

The following are the definitions of terms used in this article:

Convergence uses the following repositories to store user data. They are:

User Authentication Store:Contains user credentials. Such as user id, password, domain information, and an unique identifier to identify the user in the User or Group LDAP store.
User/Group LDAP Store (UG LDAP): Contains user preferences such as timezone that the user is in, language preference, and user theme. Convergence uses Schema 1 or Schema 2 to store user information in the User or Group LDAP.

Convergence Authentication Framework

This section describes how the authentication framework works in Sun Convergence.

The authentication module first authenticates the user in the authentication store using the configured authentication module. The default authentication module that works by default is Sun Java System Directory Server.
On successful authentication, the authentication module gets the user specific attributes like user id, the domain of the user, organization, and a unique identifier.
The authentication framework loads the user from the User Group LDAP using the user id (userID) and domain name (userDomain).

Contracts Defined by the Authentication Module

Before designing a solution for the custom authentication module, you must be aware of the contracts that the Convergence authentication framework needs for successful transfer of information between the authentication store, the Convergence authentication framework, and UG LDAP.

The authentication module must provide a mechanism to identify a user in the UG LDAP after successful authentication. The custom authentication can have any authentication store that can use any type of identifier to authenticate the user. The authentication mechanism should provide a relationship between the authenticated user and UG LDAP. After successful authentication, the authentication module should provide a unique identifier to locate the user in the UG LDAP. For example, if both authentication store and UG LDAP use the same identifier to locate the user, after successful authentication, the authentication module must set userID and userDomain parameters in the HTTP request by using callback handler objects. These parameters are used by UG LDAP filter to load the user from the UG LDAP. In our example, the user id (example scott) is the unique identifier used to locate the user in UG LDAP.

All the custom authentication modules must implement the following three classes:
- JAAS LoginModule interface. Convergence uses JAAS LoginModule as an interface for all its login modules. The custom authentication module must implement this interface. Although the authentication module uses the JAAS framework for authentication, it does not use all the advanced capabilities like authentication chaining, and multiple login modules.
- HttpCallbackHandler. An abstract class that implements the CallbackHandler of JAAS. This class must be implemented to handle custom callbacks. All custom authentication modules must implement this class to handle custom callbacks.
- Convergence uses the JAAS LoginCallback and CallbackHandler interface to get and set information between the authentication module and Convergence application. Since Convergence is a web application, authentication is performed through HTTP based request and response. Convergence provides an abstract class: HttpCallbackHandler, which implements CallbackHandler interface of JAAS.
After successful authentication, the authentication module must set the UserPrincipal object in the Subject. This can be done in commit method of login module. UserPrincipal must be created using loginID of the user.

Custom authentication modules must not create HTTP session(HTTPSession) object. Convergence authentication framework takes care of initializing the session.

About the Sample Application

This article describes the various files that are created for the custom authentication module to work. Use this as a reference to create other custom authentication modules to suite your enterprise' needs. The sample authentication module can be used as is by copying the source files and following the steps as mentioned in the following sections.

Caution
If you need to change the core class file names provided in this article, note that you must appropriately refractor the code. Some of the files use objects created by other core classes of the custom authentication module.

This example describes an authentication module for a file based user data store. The following is a sample set of data that could be used to store user information in the data store.

userinfo.txt

smith:test:siroe.com
jack:test:siroe.com
scott:test123:siroe.com

In the example, each attribute is separated by a colon. For example, the first record of the file provides information about the user id smith whose password is test with domain siroe.com.

Implementing the classes Required for the File base Authentication Store

This section describes the classes that are used to implement the authentication module for a file based user store. The following are the core class:

1. SunTestLoginModule.java
2. SunTestAuthCallBack.java
3. AppTestCallbackHandler.java

SunTestLoginModule.java

package com.sun.comms.test;

import com.sun.comms.client.logging.IwcLogger;
import com.sun.comms.client.security.auth.UserPrincipal;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
import java.util.Map;
import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.FailedLoginException;
import javax.security.auth.login.LoginException;
import javax.security.auth.spi.LoginModule;
import org.apache.commons.logging.Log;
import com.sun.comms.test.SunTestAuthCallBack;

public class SunTestLoginModule implements LoginModule {

    private Subject subject;
    private CallbackHandler cbh;
    private Map sharedState;
    private Map options;
    private boolean succeeded;
    private UserPrincipal up;
    private SunTestAuthCallBack mcb = null;
    private String credFile = "";
    private final static Log logger = IwcLogger.getLogger(IwcLogger.AUTH_LOGGER);

    public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options) {
        this.subject = subject;
        this.cbh = callbackHandler;
        this.sharedState = sharedState;
        this.options = options;
        credFile = (String) options.get("CredentialFile");
    }

    public boolean login() throws LoginException {
        Callback[] callbacks = new Callback[1];
        mcb = new SunTestAuthCallBack();
        callbacks[0] = mcb;

        if (cbh == null) {
            throw new LoginException("Error: no CallbackHandler available " +
                    "to gather authentication information from the user");
        }

        try {
            // Get userid and pwd from request
            cbh.handle(callbacks);
        } catch (Exception ex) {
            throw new LoginException("SunTestLoginModule: login failed");
        }

        String[] userInfo = attemptLogin();

        if (userInfo != null && userInfo.length==3) {
            mcb.setUserInfo(userInfo[0], userInfo[2]);
            succeeded = true;
            return true;
        } else {
            System.err.println("Unable to find user entry");
            throw new FailedLoginException("Unable to find user entry");
        }
    }

    private String[] attemptLogin() throws LoginException {

        if(credFile==null)
            throw new LoginException("User database file is not set configuration.");

        File loginFile = null;
        String userID = mcb.getUserName();
        String userPwd = mcb.getUserPwd();

        if (userID == null || userPwd == null) {
            throw new LoginException("Required user credential not found");
        }

        try {
            loginFile = new File(credFile);
            if (loginFile.exists()) {

                BufferedReader reader = new BufferedReader(new FileReader(loginFile));
                String userEntry = null;
                while ((userEntry = reader.readLine()) != null) {
                    String[] usrAcc = userEntry.split(":");
                    if (usrAcc != null && usrAcc.length == 3) {
                        if (userID.equals(usrAcc[0]) && userPwd.equals(usrAcc[1])) {
                            return usrAcc;
                        }
                    }
                }

            } else {
                System.err.println("Unable to find user database file " + credFile);
                throw new LoginException("Unable to find user database file " + credFile);
            }
        } catch (IOException ex) {
            System.err.println("Unable to load user database file " + credFile);
            throw new LoginException("Unable to load user database file " + credFile);
        }
        return null;
    }

    public boolean commit() throws LoginException {
        if (succeeded == false) {
            return false;
        } else {
            // add a Principal (authenticated identity) to the Subject
            UserPrincipal userPrincipal = new UserPrincipal(mcb.getUserName());

            if (!subject.getPrincipals().contains(userPrincipal)) {
                subject.getPrincipals().add(userPrincipal);
            }
        }
        return true;
    }

    public boolean abort() throws LoginException {
        return true;
    }

    public boolean logout() throws LoginException {
        return true;
    }
}

SunTestAuthCallBack.java


package com.sun.comms.test;

import com.sun.comms.client.security.auth.LoginCallback;
import java.io.Serializable;
import java.net.InetAddress;
import java.net.UnknownHostException;
import java.util.Locale;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;


public class SunTestAuthCallBack implements LoginCallback, Serializable {

    HttpServletRequest req;
    HttpServletResponse res;
    String username = null;
    String pwd = null;

    protected String name = null;
    protected String host = null;
    protected String user = null;
    protected String userDomain = null;
    protected Locale locale = null;
    protected String serverName = null;

    SunTestAuthCallBack(){

    }

    public void setData(HttpServletRequest request,HttpServletResponse response){
        this.req = request;
        this.res = response;
        username = (String)req.getParameter("username");
        pwd = (String)req.getParameter("password");


    }

    public String getUserName(){
        return username;
    }

    public String getUserPwd(){
        return pwd;
    }


    public void setUserInfo(String uid,String domain){
        req.setAttribute("loginID", uid);
        req.setAttribute("userDomain", domain);
    }

    public boolean setData(Object obj) {
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public Locale getLocale() {

      if (locale == null)
          return Locale.getDefault();

        return locale;
    }

    /**
     * set the client locale
     */

    public void setLocale(Locale locale) {
        if (locale != null)
            this.locale = locale;
    }

    /**
     * get the host name of the machine running the console.
     * this may be required for auditing purposes
     */

    public String getHost() {

	if (host == null) {
	    try {
                host = InetAddress.getLocalHost().getHostName();
            } catch (UnknownHostException ukhe) {
		host = null;
            }
	}

        return host;
    }

    /**
     * set the host name of the machine
     */

    public void setHost(String host) {
        if (host != null)
            this.host = host;
    }

}

AppTestCallbackHandler.java

package com.sun.comms.test;

import com.sun.comms.client.logging.IwcLogger;
import com.sun.comms.client.security.auth.modules.HttpCallbackHandler;
import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.commons.logging.Log;
import com.sun.comms.test.SunTestAuthCallBack;


public class AppTestCallbackHandler extends HttpCallbackHandler {
    private final static Log logger = IwcLogger.getLogger(IwcLogger.AUTH_LOGGER);
    public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
        if (callbacks == null) {
	    throw new IOException("Empty or null callback array");
	}

	for (int i = 0; i < callbacks.length; i++) {
             if (callbacks[i] instanceof SunTestAuthCallBack ) {
                SunTestAuthCallBack nc = (SunTestAuthCallBack)callbacks[i];
                nc.setData(request, response);
                System.err.println("request and response set in AppTestCallbackHandler");
             }else
             	System.err.println("Callback objects are not instance of SunTestAuthCallBack");
        }
    }

}

How the implementation works

For every authentication request, the Convergence authentication framework reads the configured login module class name, call back handler class name and executes it using JAAS framework.

The JAAS framework calls the initialize() method by passing all the required arguments. One of the arguments we are interested here is the Map option of the initialize() method. Convergence' authentication framework populates this object with all Misc parameters of CustomJAASService configuration.

In this example, we pass the directory location of user database CredentialFile as part of Misc parameter to SunTestLoginModule.
The other arguments are:

Subject subject - represents Subject that is being authenticated.
CallbackHandler callbackHandler - Object that is responsible for handling custom callbacks.
Map sharedState - Not used by Convergence and hence ignore it.

After successful initialization, the login module obtains all the required information about the callback handler and all the required configuration. The JAAS framework then invokes the login() method. This method performs the authentication, which is module specific. In this sample, login() method first creates callback object(s):

Callback[] callbacks = new Callback[1];
mcb = new SunTestAuthCallBack();

The call back object is aware of how to obtain the authentication related information such as the username, password, and so on. This is returned as a HTTP request. Once call back objects are created, it passes callback objects to CallBackHandler's handle method.

cbh.handle(callbacks);

callbackhandler knows how to handle call back objects. For example, the method used for callback object, the data to be passed to it, and so on.

the handle() method of callback handler then calls callback object's setData() by passing request and response objects:

SunTestAuthCallBack nc = (SunTestAuthCallBack)callbacks[i];
nc.setData(request, response);

Now, the Callback's setData() extracts the required information from request and response. In this sample, it gets request parameter username and password from request.

this.req = request;
    this.res = response;
    username = (String)req.getParameter("username");
    pwd = (String)req.getParameter("password");

The callback object now has all information that is required to authentication the user from the HTTP request. Now login method() calls an internal method attemptLogin(). This method obtains login information from the callback object:

String userID = mcb.getUserName();
        String userPwd = mcb.getUserPwd();

and loads the user database file and performs authentication. If authentication is successful this method returns String array with userID and userDomain, which is identifier to locate user in UG LDAP:

If attemptLogin() method is successful, login() method sets userID and userDomain info back into HTTP request by calling callback object's setUserInfo() method:

mcb.setUserInfo(userInfo[0], userInfo[2]);

Here, userInfo[0] is unique identified to locate user in UG LDAP. For example, uid and userInfo[2] is domain/organization name in UG LDAP under which user entry is available. This method sets this information as parameters in the HTTP request attribute:

public void setUserInfo(String uid,String domain){
        req.setAttribute("loginID", uid);
        req.setAttribute("userDomain", domain);
    }

The authentication framework uses the loginID and userDomain to get the information from the request. All custom modules must use same names for these parameters. This is mandatory for Convergence' authentication framework.

and login() method returns true.
Now JAAS framework will call commit() method of LoginModule,where UserPrincipal object is populated into authenticated Subject object. This is mandatory for Convergence' authentication framework.

UserPrincipal userPrincipal = new UserPrincipal(mcb.getUserName());

    if (!subject.getPrincipals().contains(userPrincipal)) {
         subject.getPrincipals().add(userPrincipal);
    }

Here, UserPrincipal object takes userName of the user, which is nothing but unique identifier used to locate user entry in UG LDAP.

On successful completion of the commit() method, the control goes back to Convervgence' authentication framework. This step marks the end of the authentication process. The authentication framework now has all the required information like: loginID, userDomain and authenticated Subject with UserPrincipal objects. The Convergence authentication framework then loads the user from the UG LDAP.

Compiling the sample custom module

Caution
If you need to change the core class file names provided in this article, note that you must appropriately refactor the code. Some of the files use objects created by other core classes of the custom authentication module.

Note
The paths used in the following example may differ for your installation

Create /com/sun/comms/test directory under /<some_dir>.

Note
The JAR file must be created by following the Java packaging layout rules. For example, the classes in this sample are packaged as com.sun.comms. So the Java files must be copied under the directory structure :com/sun/comms.

Copy the sample code provided earlier into the files AppTestCallbackHandler.java,SunTestAuthCallBack.java, and SunTestLoginModule.java under /<some_dir>/com/sun/comms/test directory.

Compile the java class files.

# cd /<some_dir>/com/sun/comms/test
# javac -classpath /opt/sun/comms/iwc/web-src/server/WEB-INF/lib/iwc.jar:/opt/sun/comms/iwc/web-src/server/WEB-INF/lib/commons-logging-api-1.1.jar:/opt/SUNWappserver/lib/javaee.jar  
AppTestCallbackHandler.java SunTestAuthCallBack.java SunTestLoginModule.java

Create a JAR archive.
```
cd /<some_dir>
#jar -cvf SunTestLogin.jar com
```
Note
If your custom authentication module requires any additional jar files or classes, these must be bundled along with the jar file.

Add the JAR file to deployed Convergence's libraries using Application Server's asadmin command.

asadmin set server.applications.web-module.Convergence.libraries=<path-of-customAuth-jar-file>

Note
The custom authentication module must be on the system that can be accessed by Application Server. It is best to place the JAR archive on a location outside of the Convergence installation or deployed directories. To know more see Application-Specific Class Loading in the Sun Java System Application Server 9.1 Developer's Guide.

Configuring the Sample Custom Authentication Module

This section describes the steps to configure the custom authentication module with Convergence. Since this example comes bundled with Convergence server, all you need to do to use this is to configure Convergence by setting the appropriate configuration parameters. The following are the instructions to enable the custom authentication module to use a file based authentication store.

Set the auth.custom.service name parameter in Convergence to indicate that a custom authentication module is being used.
```
./iwcadmin -w <admin_password> -o auth.custom.servicename -v "JAAS_CUSTOM"
```
Set the auth.custom.loginimpl parameter to the login module implementation created for custom authentication module.
```
./iwcadmin -w <admin_password> -o auth.custom.loginimpl -v "com.sun.comms.test.SunTestLoginModule"
```
Set the auth.custom.callbackhandler parameter to the custom callback handler used for the custom authentication module.
```
./iwcadmin -w <admin_password> -o auth.custom.callbackhandler -v "com.sun.comms.test.AppTestCallbackHandler"
```
Set the auth.misc.CredentialFile parameter to the directory where the authentication store is available. In this case, the authentication store is a file.
"Note"
Here, the value of auth.misc.CredentialFile is case sensitive. While reading these parameters inside custom authentication module the name should match the configuration.

./iwcadmin -w <admin_password> -o auth.misc.CredentialFile -v "/var/opt/SUNWiwc/config/userinfo.txt"

If you have created a custom authentication module for a different authentication store, you must follow the steps described below to enable the authentication module to work with Convergence.

Compile the custom authentication module source files and bundle them as a Java archive. See Compiling the sample custom module.
Configure Convergence to use the custom authentication module by using the steps in section Configuring the sample custom module. See
1. Set the auth.custom.service configuration parameter to "JAAS_CUSTOM".
2. Set the auth.custom.loginimpl configuration parameter to the custom login module implementation of the authentication module
3. Set the auth.custom.callbackhandler to the call back handler of the custom authentication module.
4. Set any miscellaneous parameters that you have used for your custom authentication module by setting the auth.misc configuration parameter.
Deploy the custom module. See Deploying the Authentication Module in Application Server.

Deploying the Authentication Module in Application Server

Since the authentication module is in application server's classpath, restart the applicaiton server so that the module is updated in Application Server's classpath.

Restart application server.

# /opt/SUNWappserver/bin/asadmin stop-domain domain1
# /opt/SUNWappserver/bin/asadmin start-domain domain1

Debugging and Troubleshooting the Custom Authentication Module

This section provides instructions on how to debug and troubleshoot the authentication module. For more information on debugging, see Troubleshooting Sun Convergence.

Set Convergence logging to DEBUG level.

# ./iwcadmin -w <admin_password> -o log.AUTH.level -v DEBUG

Restart the application server.

# /opt/SUNWappserver/bin/asadmin stop-domain domain1
# /opt/SUNWappserver/bin/asadmin start-domain domain1

Use the tail command to see the log messages generated.
```
# tail -f /var/opt/sun/comms/iwc/logs/iwc.log
```

Disabling the Custom Authentication Module

To change the custom authentication module to the default authentication module (LDAP) run following command.

./iwcadmin -w <admin_password> -o auth.ldap.enable -v true

Restart the application server to ensure that the changes take effect in your deployment.

# /opt/SUNWappserver/bin/asadmin stop-domain domain1
# /opt/SUNWappserver/bin/asadmin start-domain domain1

Summary

This section provides a recap of how to create a custom authentication module.

Every custom authentication module should implement the following three classes:
o A class that implements LoginModule interface
o A class that extends HttpCallBackHander class
o A(set of) class that implements CallBack interface
o If your custom authentication module requires other classes that are specific to your implementation of the authentication module, the classes must be implemented.
The iwc.jar should be there in classpath, while developing custom authentication module as it uses few Convergence specific classes like HttpCallBackHandler and UserPrincipal.
As a best practice, it is good to bundle all dependent classes in a jar file. These should be made available in the web container's class path.
Implementation of LoginModule interface and HttpCallBackHander class needs to be configured using the command line interface.
Any additional configuration specific to custom authentication module can be configured as Misc parameter using CLI
The custom authentication module must set two HTTP request attributes, userid and userDomain after successful authentication.
The userDomain must be a valid domain entry in UG LDAP under which, Convergence can uniquely locate user entry by using user id as an identifier.
The custom authentication module must create UserPrincipal object using userid and set it in Subject after successful authentication.

References

Schema Reference Guide
JAAS tutorial

Writing a Custom Authentication Module for Convergence

Writing a Custom Authentication Module for Convergence

Basic Concepts

Convergence Authentication Framework

Contracts Defined by the Authentication Module

About the Sample Application

Implementing the classes Required for the File base Authentication Store

How the implementation works

Compiling the sample custom module

Configuring the Sample Custom Authentication Module

Deploying the Authentication Module in Application Server

Debugging and Troubleshooting the Custom Authentication Module

Disabling the Custom Authentication Module

Summary

References

Labels

Comments (21)

Greg.Kimura says:

Balamurugan.k says:

jessethompson says:

Balamurugan.k says:

jessethompson says:

Balamurugan.k says:

jessethompson says:

jessethompson says:

jessethompson says:

nileshp says:

nileshp says:

jessethompson says:

DNReddy says:

jessethompson says:

hadya says:

Balamurugan.k says:

hadya says:

hadya says:

Balamurugan.k says:

jessethompson says:

DNReddy says: