Using EbaseLogonExit

Scenarios for replacing the supplied components. 6

Authentication of runtime users against an external system.. 6

EbaseLogonExit

EbaseLogonExit is a supplied logon exit module. It presents a configurable signon page to the user, where the user enters a userid and password. These are then sent to a pluggable JAAS login module which performs authentication and also has responsibility for associating the user with any roles and/or credentials.

Ebase is supplied with the following login modules:

EbaseLoginModule – authenticates against the supplied Ebase Security system (see diagram below)
LDAPLoginModule – deprecated, use LDAPLoginModule2

· LDAPLoginModule2 – authenticates against an LDAP user registry e.g. Active Directory

Logon Exit

This component is responsible for extracting a User ID and password from the end user. It receives control when a new session is detected and server property Enable Authentication Of New Users is set. The supplied logon exit performs the following functions:

· Display a logon JSP to extract User ID and password

· Route control to a JAAS login module to perform authentication.

· Save the Subject object returned by the login module for use with subsequent security authorization checks

· Display an invalid logon JSP if the logon fails

The supplied logon exit supports customer configuration of both the logon and invalid logon JSPs and the number of logon attempts.

It is possible to replace this component with a customer implementation (See Writing a Logon Exit for more information). Typically this would be used when authentication consists of something other than presenting the end user with a screen to enter their User ID/password details, e.g. the User ID is to be extracted from an HTTP header, use of digital certificates, etc. When the requirement is for the end user to enter User ID /password details and to then verify these against an external user registry, the best option is to use the supplied Ebase logon exit and replace the Login Module. See Login Module below for details.

How implemented: 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.

Plus the following servlet definition in file web.xml:

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

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

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

<init-param>

<param-name>MaxLogonAttempts</param-name>

<param-value>3</param-value>

</init-param>

<init-param>

<param-name>LogonPage</param-name>

<param-value>samples/logon/logon.jsp</param-value>

</init-param>

<init-param>

<param-name>InvalidLogonPage</param-name>

<param-value>samples/logon/logonInvalid.jsp</param-value>

</init-param>

<init-param>

<param-name>LogonTimeoutPage</param-name>

<param-value>ufs_timeout_page.htm</param-value>

</init-param>

</servlet>

<servlet-mapping>

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

<url-pattern>/LogonExitServlet</url-pattern>

</servlet-mapping>

Please note that the logon exit servlet should NOT be included within the scope of the Ebase HTTP filter.

The logon exit accepts four parameters:

· MaxLogonAttempts: the number of attempts the end user is allowed before displaying the invalid logon JSP.

· LogonPage: the logon JSP

· InvalidLogonPage: the invalid logon JSP

· LogonTimeoutPage: the logon session timeout out page

The supplied JSPs are in webapps/ufs/samples/logon and can be altered or replaced by customers to meet their requirements.

Login Module

This is a standard JAAS login module and is used to authenticate a User ID/password combination and provide a completed Subject object, which will then be used for subsequent authorization checks.

It is possible to replace this component with a customer implementation. Replacing this component allows the Ebase supplied logon exit to be used to collect the User ID/password information from the end user, but directs authentication and completion of user details to an external user registry system. The login module has two functions:

· Login: checks that a User ID/password combination is valid

· Complete: optionally supply roles and credentials to be associated with the user

Either or both of these functions can be directed to an external registry, or the Ebase UserManager component or both of these in combination.

EbaseLoginModule:

This directs both authentication and role completion to the UserManager component. This is the default login module.

LDAPLoginModule2:

See LDAP Registry options for configuration details.

How implemented:

With Tomcat,: via a JAAS login configuration file ebaselogin.config distributed in UfsServer/conf. The distributed file configures the Ebase login module.

For the Ebase login module, the login configuration file contains the following:

Ebase

{

com.ebasetech.ufs.security.authentication.EbaseLoginModule REQUIRED debug=true;

};

This file can be implemented in one of two ways:

1. By adding a line to the java.security file (this is located in jre/lib/security) as illustrated below:

Notes:

· A fully qualified path can be used e.g.login.config.url.1=file:C:/ufs/UfsServer/conf/ebaselogin.config

· Alternatively ${java.home} or {user.home} can be used to refer to the JAVA_HOME directory or the user’s home directory.

· The number following login.config.url. should be the next available number in the java.security file. This mechanism allows any number of login config files to be implemented concurrently.

· Backslashes should not be used (use forward slashes instead)

2. By adding the following property to the java command used to start the application server. This is start_ebase_server.bat in Ufs/UfsServer for the standard Tomcat system:

-Djava.security.auth.login.config==../../conf/ebaselogin.config

Notes:

· Backslashes should not be used (use forward slashes instead)

· The double equals signs are required

With Jboss:

Add the following application policy definition to the application policies at the bottom of the login-config.xml file (in Jboss/server/default/conf):

<application-policy name = "Ebase">

<login-module code="com.ebasetech.ufs.security.authentication.EbaseLoginModule" flag ="required">

<module-option name="debug">true</module-option>

</login-module>

</authentication>

</application-policy>

The application policy above configures the Ebase login module. To configure the LDAP module, replace the <login-module> section with:

<login-module code="com.ebasetech.ufs.security.authentication.LDAPLoginModule" flag ="required">

<module-option name="debug">true</module-option>

<module-option name="userManagerRoles">false</module-option>

</login-module>

see Tomcat implementation above for information on the userManagerRoles parameter.

Then add the following line to the jboss-web.xml file in the WEB-INF folder of the ufs web application. This should be added after any <resource-ref> entries.

<security-domain>java:/jaas/Ebase</security-domain>

Other Application Servers:

Most application servers provide the ability to specify a JAAS login module. This should be configured as follows:

Name: Ebase

Class: com.ebasetech.ufs.security.authentication.EbaseLoginModule or… com.ebasetech.ufs.security.authentication.LDAPLoginModule

Required: true

Parameters: Name: debug Value: true

If the application server does not allow the login module entry name to be specified (e.g. Oracle Application Server), this name can be specified server property Login Module Entry Name. This parameter has a default value of Ebase.

User Manager

This component accesses the Ebase security database, and implements two main methods which are called in turn by the login module for runtime users and by the Ebase Designer for designer users:

boolean authenticate(String userId, String password)

This method answers true if authentication is successful.

completeSubject(Subject subject, String userId)

This method completes the supplied JAAS Subject object with information about the user. This information includes all the roles associated with the user. These roles will be used for subsequent authorization checks. Specifically, this method adds a com.ebasetech.ufs.security.authentication.UserPrincipal object to the subject. This UserPrincipal contains the User ID. It also adds one com.ebasetech.ufs.security.authentication.RolePrincipal object for each security role associated with the user. Each RolePrincipal contains a single role name.

This component can be replaced.

How implemented: via server property User Manager Class Name.

Scenarios for replacing the supplied components

A number of scenarios are possible:

Authentication of runtime users against an external system

In this scenario, the requirement is to authenticate runtime users against an external system, but to use the Ebase Security System for designer users. This is most easily achieved by replacing the Login Module. The replacement should call the external system instead of the User Manager.

Note that the Login Module implementation must create a UserPrincipal object as described earlier and add this to the Subject. In addition, if runtime security is used or if the Ebase Workflow system is used, RolePrincipal objects representing a role to be associated with the user must also be added. There are two alternatives for this:

1. Define the users and their associated roles in the Ebase Security System.

2. Extract the role names from the external system, in which case the external system must have some means of modelling role associations for a user.

In both cases, the role names refer to roles defined in the Ebase Security System. Each of these roles consists of one or more authorizations.

Use of application server security

Application server security can be used to supply an authenticated User ID. The Http filter component checks for an application server provided User ID using request.getRemoteUser(). If a User ID is supplied, it will be used, and no configuration is required to achieve this. The result of this is a Subject object containing a UserPrincipal but no RolePrincipals.

If runtime authorization checking is also required, any roles associated with the user must also be extracted. The system will automatically try to complete these role associations by calling UserManager.completeSubject(). If the Ebase supplied UserManager is used, this will extract any roles defined in the Ebase Security system. However, this technique would involve duplication of User ID definitions. Alternatively, role associations could be extracted from an external system by a logon exit. If a logon exit is configured, it will be called even if an application server User ID has been provided. This logon exit could then extract the role associations from an external system and add these to the Subject object.

Use of Windows User ID

This scenario is possible within a networked Windows environment where all users are authenticated. In this scenario, it is not required to display sign on screens to the end user. All that is required is to extract the Windows User ID and treat the user as authenticated. For Tomcat systems using IIS as web listener, this can be achieved by setting the following parameter in the jk2.properties file:

tomcatAuthentication=false

It is not necessary to use a logon exit. Note that in this scenario, the Ebase system will remove any domain information from the User ID passed from IIS, e.g. mydomain\Betty will result in user Betty. Users can additionally be defined in the Ebase Security System. When this is done, roles associated with the user are extracted at logon and can then be used for subsequent security authorization checks.