Write your own handler and integrate it into CAS GH

It is very easy to write a new handler exactly meeting your requirements, and the integration of your handler can be done without modifying the existing code.

We show below an example.

Write a new handler

We want to write a very simple handler, that only authenticates one single user, with a password.

Choose a name

Choose a name for your handler, for instance org.esupportail.cas.server.handlers.ExampleHandler. The source of your handler will then be located in source/org/esupportail/cas/server/handlers/ExampleHandler.java.

Specify the XML configuration

The XML configuration of a handler looks like:

<authentication>
  <handler>
    <classname><!-- handler classname goes here --></classname>
    <config>
      <!-- handler configuration parameters go here -->
    </config>
  </handler>
</authentication>

For our needs, we will have:

<authentication>
  <handler>
    <classname>org.esupportail.cas.server.handlers.ExampleHandler</classname>
    <config>
      <login><!-- user's login goes here --></login>
      <password><!-- user's password goes here --></password>
    </config>
  </handler>
</authentication> 

Write the class

The ExampleHandler class should inherit from BasicHandler, and implement the constructor and the authenticate() method:

package org.domain.cas.server.handlers.example;
             
import org.dom4j.Element;
import org.esupportail.cas.server.util.BasicHandler;

/**
 * This class implements a very simple handler accepting one
 * particular login/password.
 *
 * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>
 */
public final class ExampleHandler extends BasicHandler {
   
    /** the only netId that the handler will accept */
    private String login;
   
    /** the associated password */
    private String password;

    /**
     * Analyse the XML configuration to set netId and password attributes (constructor).
     * 
     * @param handlerElement the XML element that declares the handler in the configuration   file
     * @param configDebug debugging mode of the global configuration (set by default   to the handler)
     * 
     * @throws Exception when the handler not configured correctly
     */
    public ExampleHandler(
                          final Element handlerElement, 
                          final Boolean configDebug) throws Exception {
        super(handlerElement, configDebug);
        traceBegin();
     
        // check that a config element is present
        checkConfigElement(true);
   
        // get the configuration parameters
        login = getConfigSubElementContent("login", true/*needed*/);
        trace("login = " + login);
        password = getConfigSubElementContent("password", true/*needed*/);
        trace("password = " + password);
     
        traceEnd();
    }
   
    /**
     * Try to authenticate a user (compare with the local credentials). 
     *
     * @param userLogin the user's login
     * @param userPassword the user's password
     *
     * @return BasicHandler.SUCCEDED on success, 
     * BasicHandler.FAILED_CONTINUE or BasicHandler.FAILED_STOP otherwise.
     */ 
     public int authenticate(
                             final String userLogin,
                             final String userPassword) {
         traceBegin();
   
         trace("Checking user's login...");
         if (userLogin.equals(login) && userPassword.equals(password)) {
             trace("Users's login matches, checking user's password...");
             if (userPassword.equals(password)) {
                 trace("User's password matches.");
                 traceEnd("SUCCEEDED");
                 return SUCCEEDED;
             } else {
                 trace("User's password does not match (no more handler should be tried).");
                 traceEnd("FAILED_STOP");
                 return FAILED_STOP;
             }
         } else {
             trace("User's login does not match (another handler can be tried).");
             traceEnd("FAILED_CONTINUE");
             return FAILED_CONTINUE;
         }
    }
}

This ExampleHandler.java example is included into the esup-casgeneric distribution.

In our example, we use the getConfigSubElementContent() method, which is a convenient way to get the content of a first-level XML config element. Of course, you can do anything you want with the org.dom4J.Element instance that is provided.

Note: if you plan to write a more sophisticated handler based on many redundant servers, then you should have a look at similar handlers, such as NisHandler.

Integrate your handler

Run the deploy ant target, nothing more has to be done!

If you think your handler can be used by other people, please send it to the casgeneric-users@esup-portail.org mailing list.

Thanks in advance.