/** ****************************************************************************
 *
 * Copyright (c) 2001-2004 Tortuga Technologies Pty Ltd. All rights reserved.
 *
 * This is unpublished proprietary source code of Tortuga Technologies Pty Ltd.
 * The copyright notice above does not evidence any actual or intended
 * publication of such source code.
 *
 *******************************************************************************
 *
 * File: au.com.tortuga.ozibug.auth.example.IPAuthenticationHandler.java
 *
 * Description: Example IP Address Based Single Sign On Authentication handler
 *
 **************************************************************************** */

package au.com.tortuga.ozibug.auth.example;

// application specific imports
import au.com.tortuga.ozibug.auth.AuthenticationHandler;
import au.com.tortuga.ozibug.util.LifeCycle;

// external imports
import org.apache.log4j.Category;

// servlet imports
import javax.servlet.http.HttpServletRequest;

// java imports
import java.util.Iterator;
import java.util.Map;


/** ****************************************************************************
 *
 * This <strong>example</strong> Authentication Handler shows how a simple
 * Single Sign On capability can be added to Ozibug.
 * This handler simply reads in a set of <strong>host/username</strong> or
 * <strong>address/username</strong>mappings at initialization time and then
 * tries to authenticate each request based on its host name or address.
 * <p>
 *  The following properties show examples of configuration.
 * </p>
 * <pre>
 * authentication.handler.1=au.com.tortuga.ozibug.auth.example.IPAuthenticationHandler
 * authentication.handler.1.parameter.1=host1.yourdomain.com=developer1
 * authentication.handler.1.parameter.2=host2.yourdomain.com=developer2
 * authentication.handler.1.parameter.3=10.10.10.22=manager
 * authentication.handler.1.parameter.4=127.0.0.1=admin
 * </pre>
 *
 * @author Tortuga Technologies
 *
 **************************************************************************** */
public class IPAuthenticationHandler implements AuthenticationHandler,LifeCycle {

  /** **************************************************************************
   * 
   *  Class (static) variables - public/protected/package/private
   *
   ************************************************************************** */

  /** logging category */
  private static final Category log =
    Category.getInstance(
      "au.com.tortuga.ozibug.auth.example.IPAuthenticationHandler" );

  /** the name of this handler (IP) */
  private static final String NAME = "IP";

  /**
   * a description of how this handler authenticates (ip-address or hostname
   * of request mapped to user name)
   */
  private static final String DESCRIPTION =
    "uses ip-address (or hostname) of request to lookup username";


 /** **************************************************************************
  *
  * Instance variables - public/protected/package/private
  *
  ************************************************************************** */

  /** holds the mappings of hostname to username, or address to username */
  private Map addressMap = null;


  /** **************************************************************************
   *
   * Called on initialization this method prints out configuration and
   * stores it away for later use.
   *
   * @param handlerInfo configuration information
   * @see LifeCycle#init
   *
   ************************************************************************** */
  public void init( Map handlerInfo ) {

    String logId = "init";

    // print the mapping configuration
    Iterator it = handlerInfo.keySet().iterator();
    while ( it.hasNext() ) {
      String name  = (String) it.next();
      String value = (String) handlerInfo.get( name );
      log.debug( logId + ": " + name + " = " + value );
    }

    // save the map
    this.addressMap = handlerInfo;

  } // init


  /** **************************************************************************
   *
   * Called when the Ozibug servlet is terminated by the container.
   *
   * @see LifeCycle#destroy
   *
   ************************************************************************** */
  public void destroy() {
  } // destroy


  /** **************************************************************************
   *
   * Returns the name of this Authentication Handler.
   *
   * @return the name of this authentication handler
   * @see AuthenticationHandler#getName
   *
   ************************************************************************** */
  public String getName() {
    return NAME;
  } // getName


  /** **************************************************************************
   *
   * Returns a description of this Authentiction Handler.
   *
   * @return a brief description of how this authentication handler works
   * @see AuthenticationHandler#getDescription
   *
   ************************************************************************** */
  public String getDescription() {
    return DESCRIPTION;
  } // getDescription


  /** **************************************************************************
   *
   * Try to map the hostanme or ip address of the incoming request to a user
   * name through the address map configured at initialization.
   *
   * @param context the context used to pass objects between handlers
   * @return true if an authentication was achieved; false otherwise
   * @see AuthenticationHandler#authenticate
   *
   ************************************************************************** */
  public boolean authenticate( Map context ) {

    String  logId  = "authenticate";
    boolean result = false;

    try {

      // get the request
      HttpServletRequest req = (HttpServletRequest) context.get( HTTP_REQUEST );
      if ( req != null ) {

        String id = null;

        // try for an host address
        String host = req.getRemoteHost();
        if ( host != null ) {
          id = (String) addressMap.get( host );
        }
        else {
          // try for an ip address
          String addr = req.getRemoteAddr();
          if ( addr != null ) {
            id = (String) addressMap.get( addr );
          }
        }

        if ( id != null ) {
          // mapped incoming request to user name, set the return result to true
          result = true;
          // set the authenticated user id into the context
          context.put( USER_NAME, id );
        }
      }

    }
    catch ( Exception e ) {
      // unexpected exception while processing, log it and continue
      log.error( logId + ": failed, " + e, e );
    }

    // return the status of this authentication attempt
    return result;

  } // authenticate


} // IPAuthenticationHandler