au.com.tortuga.ozibug.auth
Interface AuthenticationHandler

public interface AuthenticationHandler

This interface must be implemented by classes which take part in the Ozibug authentication mechanism.

The authentication process takes place when a new incoming HTTP Request is detected. An authentication context is created and the HTTP Request is placed in it. The authentication mechanism will then execute each module (or link) in the chain of authentication handlers in turn. Each module is given the authentication context so that it can examine the contents (the HTTP Request), and carry out the authentication. If the authentication module succeeds then the validated user name is placed in the context and the handler returns the value true; otherwise it should return the value false.

Following successful authentication, the authorization and access control processes will be invoked to ensure the user is authorized to access Ozibug and will determine their access level. Once this is complete a successful login to Ozibug has occurred and the standard welcome page will be presented.

The default authentication handler chain is comprised of the following modules.

1. Standard - authentication is performed against the user details held in Ozibug based on the user id and password supplied in the HTTP request.
2. Key - authentication is performed against the user details held in Ozibug based on the single access key supplied in the HTTP request (used by the reporting module.)
3. TmpLogin - authentication is performed against the user details held in Ozibug based on the user id and temporary password supplied in the HTTP request (used by the forgotten password module.)

A default Ozibug installation will use the default authentication handler chain out of the box. To change this behaviour open the OZIBUG_HOME/WEB-INF/ozibug.properties file with your favourite editor and configure the authentication.handler.chain property. The configuration allows the names of custom and/or default handlers to be included in any order. The handler names should be specified as a comma separated list, in which the order is significant. The default authentication handler chain is equivalent to setting the property as follows.

  authentication.handler.chain=Standard,Key,TmpLogin
  

Additional properties can be set for each custom authentication handler to allow for configuration of its behaviour. At a minimum the fully qualified class name of the handler must be supplied, along with any number of optional parameters to configure attributes such as a database connection. For example, the configuration required for the example LDAP authentication handler would be similar to the following.

 authentication.handler.1=au.com.tortuga.ozibug.auth.LDAPAuthenticationHandler
 authentication.handler.1.parameter.1=ldap.host=myHost.myDomain
 authentication.handler.1.parameter.2=ldap.port=389
 authentication.handler.1.parameter.3=ldap.bind.dn=cn=Manager,o=Tortuga Technologies
 authentication.handler.1.parameter.4=ldap.bind.passwd=mypassword
 authentication.handler.1.parameter.5=ldap.search.base=o=Tortuga Technologies
 authentication.handler.1.parameter.6=ldap.search.filter=(&(uid={0})(objectclass=inetorgperson))
 

Multiple authentication handlers can be specified by incrementing the numeric suffix for each handler. The suffixes must be contiguous. The example below shows three handler definitions.

 authentication.handler.1=au.com.tortuga.ozibug.auth.SSOAuthenticationHandler
 authentication.handler.2=au.com.tortuga.ozibug.auth.LDAPAuthenticationHandler
 authentication.handler.3=au.com.tortuga.ozibug.auth.IPAuthenticationHandler
 

The parameters are also specified in the same manner with the numeric suffix being incremented for each definition.

 authentication.handler.1=au.com.tortuga.ozibug.auth.MyAuthenticationHandler
 authentication.handler.1.parameter.1=name1=value1
 authentication.handler.1.parameter.2=name2=value2
 authentication.handler.1.parameter.3=name3=value3
 

Notes:

• Setting the handler chain property overrides the default behaviour, therefore any default handlers required must be included in the required order.
• Changes to any of the handler properties will require a restart of the servlet container before the changes take effect.
• The class files for any custom authentication handlers must be placed in the classpath of the Ozibug context, by either including them in a jar and adding it to the lib directory (eg., OZIBUG_HOME/WEB-INF/lib/myhandlers.jar) or by adding the class itself to the classes directory (eg., OZIBUG_HOME/WEB-INF/classes/myDomain/myPackage/MyAuthenticationHandler.class).

Author:

Tortuga Technologies

Field Summary

static java.lang.String	FAILURE_DETAILS name of key to used to set the failure details into the context
static java.lang.String	HTTP_REQUEST name of key to obtain the current HttpServletRequest object from the context
static java.lang.String	USER_NAME name of key to used to set the validated username into the context

Method Summary

boolean	authenticate(java.util.Map context) Authenticate the incoming request given the authentication context; this contains the HttpServletRequest contained under the au.com.tortuga.ozibug.auth.Authentication.HTTP_REQUEST key and if authentication is successful this method should put the user id under the au.com.tortuga.ozibug.auth.Authentication.USER_NAME key in the context before returning.
java.lang.String	getDescription() Return a brief description of how this authentication handler works; eg, what it's expecting in the context (perhaps nothing) and how it derives a username.
java.lang.String	getName() This method is invoked to get the name of the AuthenticationHandler which is then used to configure the chain of handlers; A brief (whitespace-less) String is recommended.

Field Detail

HTTP_REQUEST

public static final java.lang.String HTTP_REQUEST

name of key to obtain the current HttpServletRequest object from the context

See Also:

Constant Field Values

USER_NAME

public static final java.lang.String USER_NAME

name of key to used to set the validated username into the context

See Also:

Constant Field Values

FAILURE_DETAILS

public static final java.lang.String FAILURE_DETAILS

name of key to used to set the failure details into the context

See Also:

Constant Field Values

Method Detail

getName

public java.lang.String getName()

This method is invoked to get the name of the AuthenticationHandler which is then used to configure the chain of handlers; A brief (whitespace-less) String is recommended.

Returns:

the name of this handler such as "IP", "Key" or "JCSI_SSO"

getDescription

public java.lang.String getDescription()

Return a brief description of how this authentication handler works; eg, what it's expecting in the context (perhaps nothing) and how it derives a username.

Returns:

a brief (one line) description

authenticate

public boolean authenticate(java.util.Map context)

Authenticate the incoming request given the authentication context; this contains the HttpServletRequest contained under the au.com.tortuga.ozibug.auth.Authentication.HTTP_REQUEST key and if authentication is successful this method should put the user id under the au.com.tortuga.ozibug.auth.Authentication.USER_NAME key in the context before returning. When an authentication fails significantly then the key au.com.tortuga.ozibug.auth.Authentication.FAILURE_DETAILS can be used to feed back information about the error to the user.

Parameters:

context - the context used to pass objects between handlers

Returns:

true if an authentication was achieved; false otherwise