Ebase Security Authentication

HTTP Filter. 2

Logon Exit 2

User Manager. 4

Scenarios for replacing the supplied components. 5

Authentication of runtime users against an external system.. 5

Authentication of all users against an external system.. 5

Use of application server security. 5

Use of Windows User ID.. 5

Ebase Designer considerations. 5

The Ebase system supports authentication of both Ebase Designer users, and users of the runtime system (i.e. users running forms). The system is shipped with a built-in system for handling the maintenance of user definitions and subsequent authentication, which handles both designer and runtime security. However, this system or individual components of the system can be replaced to enable one or more functions to be handled by external systems.

This document describes the functions performed by the supplied Ebase components, and the options available for replacing these.

Required security object model

The Ebase system allows most of the supplied authentication components to be replaced. However, at the conclusion of the logon process, a JAAS Subject object (javax.security.auth.Subject) is required that represents the authenticated user. This must contain a com.ebasetech.ufs.security.authentication.UserPrincipal object that represents the User ID.

Additionally, if runtime authorization checks are required, one com.ebasetech.ufs.security.authentication.RolePrincipal object is required for each security role associated with the user. Each RolePrincipal contains a single role name. These Principal objects are added to the Subject object with method getPrincipals().add(principal).

The Subject object is then used by other security components within the Ebase system e.g. security authorization checks, Ebase Workflow etc.

Supplied Authentication Components

The diagram below shows the supplied Ebase components used for authentication.

HTTP Filter

This program intercepts all HTTP requests for the Ebase system. When a new HTTP session is detected, it performs the following:

· checks whether the form is submitted from the Ebase Designer and if so, uses the designer’s Subject object, bypassing any sign-on dialog box.

· checks whether a User ID has been supplied by application server security. If so, calls completeSubject() on UserManager to add any roles defined for the user in the Ebase Security System.

· checks whether a User ID has been supplied by an old-style logon exit. If so, it calls completeSubject() on UserManager to add any roles defined for the user in the Ebase Security System.

· routes control to a logon exit, if configured.

This component cannot be replaced. Its use can, however, be extended to include additional servlets and/or JSPs. This could be used where customer-written programs are front-ending the Ebase system.

How implemented: via the web.xml deployment descriptor in webapps/ufs/WEB-INF.

Logon Exit

This component is responsible for extracting a User ID and password from the end user. It receives control from the HTTP filter program EbaseFilter when a new session is detected and a logon exit is specified in UFSSetup.properties. 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: using the following line in UFSSetup.properties:

Ufs.logonExitServlet=LogonExitServlet

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 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.

The Ebase system is shipped with two login modules, EbaseLoginModule (the default) and LDAPLoginModule.

Additional attributes (e.g. email, manager, department etc) can also be extracted from a LDAP registry system. (See Extracting Attributes from an LDAP Registry)

EbaseLoginModule:

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

LDAPLoginModule:

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 using parameter Ufs.loginModuleEntryName of UFSSetup.properties. 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 the following line in UFSSetup.properties:

Ufs.userManager=com.ebasetech.ufs.security.authentication.EbaseUserManager

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. (See Ebase Security Authorization for more information)

Authentication of all users against an external system

In this scenario, the requirement is to authenticate all users including designer users against an external system. This is achieved by replacing the User Manager component. In this case, the external system must have some means of modelling role associations and the User Manager must implement the isDesignerUser() method to determine whether a logon to the Ebase Designer is possible.

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.

Ebase Designer considerations

To access the Ebase Designer, a user must have the following authorization:

Type: DESIGNER

Name: LOGON

Function: Read

At least one additional authorization is required to grant access to the various elements within the Ebase Designer. (See Ebase Security Authorization for more information)

In the supplied system, users are defined using the Ebase security dialog, and are authenticated using the Ebase provided Login Module as described above. If the Login Module is replaced, for example to authenticate against Active Directory, then all user definitions are held externally. However, we still need to associate a user with at least one role in order to grant the authorizations required to access Ebase Designer. This completion of roles associated with a user could be done in one of two ways:

1. By additionally defining each user in the Ebase Security System and adding roles to the user definition or group definitions. To achieve this, the commit() method of the Login Module should call commitSubject() on the Ebase User Manager. However, this technique represents some duplication of user maintenance.

2. By maintaining the association of roles within the external system, e.g. as a comma delimited list. These could be extracted by the Login Module and added to the Subject object as RolePrincipal objects.

As an alternative, it is also possible to direct authentication for runtime users to the Login Module component, but direct authentication for designer users to the User Manager component. In this scenario, designer users can be defined and maintained using the supplied Ebase security system, whereas runtime users are defined externally. This is achieved by specifying the following parameter in UFSSetup.properties:

Ufs.useUserManagerForDesignerAuthentication=true