Xi Logon Exit

Documentation home

 

Description. 1

Implementation. 3

1.       Write and test the Logon Service. 3

2.       Configure the XIsecurity properties file. 3

3.       Enable the logon exit 6

 

 

See also: Implementing the Logon Service, Runtime Authentication

 

Description

XILogonExit is a supplied logon exit that invokes the implemented Logon Service to logon a user. When configured, the logon exit is invoked automatically when a user first connects to the system as shown in the diagram below. The logon exit can be configured to obtain user related information from the Http Request document e.g. from request headers, request parameters or cookies, or it can be configured to display a JSP where the user enters userid/password details. This user related information is then passed to the Logon Service where it is used to authenticate the user.

 

The logon exit can also be used in conjunction with the Xi workflow assignment handler to provide a simple and flexible technique for handling workflow assignment.

 

         

 

The steps are as follows:

 

1.      User request received to run form MYFORM1.

2.      XILogonExit is invoked automatically when runtime security is enabled and a request is received from an unauthenticated user.

3.      XILogonExit extracts information from the request URL and invokes the Logon Service.

4.      The Logon Service logs the user on to the system and can also extract additional role and credential information. 

5.      MYFORM1 is then invoked.

 

This scenario is applicable when user related information is available on the URL, which is typically the case when using some sort of central user registry such as Active Directory or when using a single sign-on system. XILogonExit also provides options to allow the user to manually enter authentication details, usually userid and password.

 

XILogonExit provides the ability to extract user related information from the request URL – this might be a userid or some sort of token representing the userid. The following options are supported as standard:

 

·         Extract information from a request parameter

·         Extract information from the request header

·         Extract information from a cookie.

 

As a special case, information from the HttpServletRequest object can be queried using request header variables. This can be used for all get… methods on HttpServletRequest that return a String. For example:

  • Request header variable remoteUser provides the userid set by the application server (by invoking the getRemoteUser() method on HttpServletRequest)
  • Request header variable remoteAddr provides the requester’s IP address (by invoking the getRemoteAddr() method on HttpServletRequest)

See Javadoc on HttpServletRequest for details of additional get.. methods.

 

 (Additional sources of user information can be configured by extending the implementing Java classes. Contact Ebase support for information on how to do this.)

 

Role and credential information can be added to the user security definition, and this can be used later by applications: to resolve security authorizations, to supply user attributes e.g. email address, or to control workflow assignment.

 

 

 

Implementation 

The steps to implement XILogonExit to meet the security requirements of your organisation are:

 

  1. Write and test the Logon Service
  2. Configure the XIsecurity. properties file
  3. Enable the logon exit

 

1.    Write and test the Logon Service

Click here for details.

2.    Configure the server security properties

These properties are in section XI Logon Exit User Source Parameters of Server Security Properties:

 

Parameters relating to the source of security information:

 

Logonexit.ParameterName1

Logonexit.ParameterSource1

Logonexit.ParameterName2

Logonexit.ParameterSource2

Logonexit.ParameterName3

Logonexit.ParameterSource3

 

These 6 properties represent 3 parameters where each parameter is a name/source combination. Each one of these 3 parameters controls where a specific piece of information about the user can be found. The source properties must be one of URL, HEADER or COOKIE. The system extracts the value for each parameter from the HTTP request and passes this to the Logon Service as shown in the examples below:

 

Example 1: User information passed on the URL:

 

Here we assume that the usertoken parameter has been added to the URL. The script implementing the logon exit does the job of translating this into a userid.

 

URL: http://www.mycorp.com/ebase/MyForm.eb?usertoken=973765AB34

 

Logonexit.ParameterName1=usertoken

Logonexit.ParameterSource1=URL

 

This will result in the following input fields to the web service (see request document format below):

PARAM1_VALUE=973765AB34

PARAM1_SOURCE=URL

 

Example 2: User information passed as request header variable:

 

Here we are extracting the userid set by the application server. This can be configured to contain the Windows domain userid.

 

Logonexit.ParameterName1=remoteUser

Logonexit.ParameterSource1=HEADER

 

This will result in the following input fields to the web service – where the userid is jxsmith (see request document format below):

PARAM1_VALUE= jxsmith

PARAM1_SOURCE=HEADER

 

 

Example 3: User information passed using cookies:

 

In this example we will assume that 2 cookies have been created:

 

Officeloc : provides the usual office location of the user, and has the value London

Userref : provides a personnel number or some other user reference, and has the value 753864

 

In this example we have an imaginary company that has implemented different security systems for different parts of the organisation (represented by cookie officeloc). Userref might represent a userid for one office location or a personnel number for another location.

 

Logonexit.ParameterName1=Officeloc

Logonexit.ParameterSource1=COOKIE

Logonexit.ParameterName1= Userref

Logonexit.ParameterSource1=COOKIE

 

This will result in the following input fields to the web service (see request document format below):

PARAM1_VALUE=London

PARAM1_SOURCE=COOKIE

PARAM1_VALUE=753864

PARAM1_SOURCE=COOKIE

 

Parameters relating to user input

User input in this heading means that the user is presented with a panel where security data – usually userid and password – can be manually entered. If user information is extracted from the URL as described above, the Logonexit.InputFromUser parameter should be set to false.

 

These properties are in section Xi Logon Exit General Properties of Server Security Properties:

 

Logonexit.InputFromUser

Set this to either true or false (the default is false). When true the HTML or JSP page specified by the next property is displayed so the user can manually enter authentication details: usually userid and password.

 

Logonexit.LogonPage

The URL of the HTML or JSP page presented to the user. This page can have up to three input fields whose names are supplied in properties Logonexit.UserParm1, Logonexit.UserParm2 and Logonexit.UserParm3. In most cases this page will contain userid and password fields. The default is samples/logon/logon.jsp which contains userid and password.

 

Logonexit.MaxLogonAttempts

The maximum number of manual logon attempts allowed (the default is 3)

 

Logonexit.UserParm1

The name of the first user enterable field. e.g. e_username in <input type="text" value="" size="30" name="e_username">

The default is e_username.

 

Logonexit.UserParm2

The name of the second user enterable field. See Logonexit.UserParm1. The default is e_password.

 

Logonexit.UserParm3

The name of the third user enterable field. See Logonexit.UserParm1. The default is jsp_param3.

 

 

Other properties

These properties are in section Xi Logon Exit General Properties of Server Security Properties:

 

Logonexit.InvalidLogonPage

The URL of the HTML or JSP page presented to the user when logon fails. The default is samples/logon/logonInvalid.jsp.

 

Logonexit.WebServiceUrl

The URL of the system web service LOGON_SERVICE. The default is an internal URL to access the service on the same server. You should normally only specifiy this parameter when the logon service is implemented on a remote server, and then the URL should be of the type http://domain[:port]/webapp/integration/ebaseLogonService.

 

Logonexit.LogonPageCode

This is the error code returned by the system web service to indicate that the user must signon manually and the logon page defined by property Logonexit.LogonPage should be displayed. Typically this would be used if input is normally via URL/HEADER/COOKIE parameters, but it has not been possible to validate the userid for some reason. The default for this parameter is JSP.

 

Logonexit.TimeoutPage

This page is displayed in the event of a timeout. Note that this page can also be displayed if the browser back button is used after logon has been successful to return to the logon page. The default is ufs_timeout_page.htm.

 

 

3.    Enable the logon exit

 

  1. Edit file web.xml in directory WEB-INF of the web application. Locate the definition of the LogonExitServlet and change the class name to com.ebasetech.ufs.xi.security.authentication.XILogonExitServlet as shown below:

 

<servlet>

   <servlet-name>LogonExitServlet</servlet-name>

   <display-name>LogonExitServlet</display-name>

   <servlet-class>com.ebasetech.ufs.xi.security.authentication.XILogonExitServlet</servlet-class>

</servlet>

 

This is the default as shipped with the system.

 

  1. Set server property Enable Authentication Of New Users. This is the master switch that activates the logon exit. With this property set, unauthenticated users are not allowed access to the server.