Jaffa has been fully tested under the Jakarta Tomcat web server. We have been using this web server since Tomcat 3.3, when we first started Jaffa.

It is not the scope of this page to cover all the configuration aspects of Tomcat security, you can buy a book for that, (or gleam it from various internet sites). However some of the basic tomcat stuff will be covered here.

All though the Jaffa project tries not to be web server specific, what is covered here is specifically for Tomcat, and the new Authentication Realm we have develop is specifically for Tomcat, but could be developed for other containers that provide this level of extention.

The contents for the rest of the page are...

• Single Sign-On
• Setting Up The Tomcat Realm
• Writing and Using an EncryptionClass
• Dealing with MBeans

It is also worth looking at the session management stuff as this ties into the authetication process.

Assumptions

We will assume for now that you know how to install Tomcat and how to deploy a web application to it. We also assume some familiarity with the WAR file structure, in particular the web.xml file that controls the configuration of your deployed web application.

We recommend that you look into using SSL with Tomcat, and possible address other server issues. For this either use the web, or read the Tomcat Security Handbook

Traditionally users have had to sign-on to multiple systems, each of which may involve different usernames and authentication techniques. In contrast,with single sign-on, the user needs to authenticate only once and the authenticated identity is securely carried across the network to access resources on behalf of the user. "Single sign on support" implementation utilizes cookies to maintain user identity across applications, the same risks of information exposure apply here as when cookies are used to maintain session identity within a single web application. If you are concerned that attackers may try to impersonate an ongoing session, you should run across a secure network connection (such as an SSL connection using the https protocol). This session cookie is maintained until the web browser is shut down.

As the vision with Jaffa is that applications developed with it will be predominantly web based, and exist in enterprise environments, there is a strong possibility that it will need to integrate with other web apps. We have assumed from the outset that integration with a Web Portal to be a critical part of this enterprise level integration and for that reason, single sign-on as well as single point user administration are key areas for Jaffa based applications.

Configure Single Sign-On Authentication on Tomcat 4.x

1. Edit the Tomcat configuration file

   This file is stored at "%CATALINA_HOME%/conf/server.xml". This is what the new "valve" should look like. You can edit and un-comment this valve in the server.xml file.

   In server.xml, this is nested in the <Host> element
   <Valve className="org.apache.catalina.authenticator.SingleSignOn" debug="0" />

   Requirements and Assumptions

   • Make sure you are running Java JDK 1.4, or using the JSSE extension for older versions of the JDK.

   • For Windows installation

     %CATALINA_HOME% refers to the directory into which you have installed Tomcat 4. %JAVA_HOME% refers to the directory into which you have installed JDK 1.4
     
     

   • For UNIX installation: $CATALINA_HOME refers to the directory into which you have installed Tomcat 4. $JAVA_HOME refers to the directory into which you have installed JDK 1.4.
     
     

For container authentication you need to define configure a Realm in server.xml to perform the authentication. There is plenty of information on how to use the standard realms that come with tomcat (see How To for v4.1.x).

In this section we will talk about setting up the Tomcat with the new JDBCEncryptionRealm, which has been developed as under the Jaffa Project.

This is an extention of the standard JDBCRealm, but has been enhanced with the following features

• Supports validation using custom password encryption code. An EncryptionClass and EncryptionMethod can be specified, and the password is run through this method before being compared to the database value (allowing one-way encryption algorithms to be used if necessary).

• Allows for additional criteria to be added to the retrieve of the user record, not just the user's id. For example, if you have a 'status' field on your USERS table, and when set to 'INVALID', you don't want users to be authenticated, you can add the clause status != 'INVALID' to the query.

• Allows for an alternative query to be specifed to read the roles, in the event you don't want to create a special view (which is recommended in the documentation for the JDBCRealm). In this case you may have a USERS table with USER_NAME field, and a USER_ID field (technical key), and a ROLES table with ROLE_NAME and a ROLE_ID field (technical key). The resolving table would be USER_ROLES with fields USER_ID and ROLE_ID. In reality the Realm really wants to read a resolving table with USER_NAME,ROLE_NAME. In this case you could specify the query to use to be select a.role_name from roles a, user_roles b, users c where c.user_name = ? and b.user_id = c.user_id and a.role_id = b.role_id

• Allows for validation in the case of null passwords in your data source (Not normally recommended)

• Generates an error if the user id key you specify returns more that one distinct row (Which shouldn't be the case ig the user name is a unique key!)

There is a build target in the \build.xml called jaffa-tomcat.jar which will build the JAR file needed for deployment. You must place this JAR in the %CATALINA_HOME%/server/lib folder, along with any other JAR that contains a custom Encryption class, if one is being used (see later).

An Example configuration in server.xml looks like...

    <Realm
        className          ="org.jaffa.tomcat.realm.JDBCEncryptionRealm"
        debug              = "99"
        driverName         = "com.microsoft.jdbc.sqlserver.SQLServerDriver"
        connectionURL      = "jdbc:microsoft:sqlserver://myhost:1433;DatabaseName=mydb;SelectMethod=cursor"
        connectionName     = "myschema"
        connectionPassword = "pass"
        userTable          = "users"
        userNameCol        = "user_name"
        userCredCol        = "password"
        roleSelect         = "select a.role_name from roles a, user_roles b, users c
                              where c.user_name = ?
                              and b.user_id = c.user_id
                              and a.role_id = b.role_id"
        encryptionClass    = "com.mycompany.service.Encrypt"
        encryptionMethod   = "encrypt"
    />

    <Realm
        className          = "org.jaffa.tomcat.realm.JDBCEncryptionRealm"
        debug              = "0"
        driverName         = "oracle.jdbc.driver.OracleDriver"
        connectionURL      = "jdbc:oracle:thin:@myhost:1521:mydb"
        connectionName     = "myschema"
        connectionPassword = "pass"
        userTable          = "user"
        userNameCol        = "user_name"
        userCredCol        = "password"
        userClause         = "status!='INACTIVE'"
        userRoleTable      = "user_roles"
        roleNameCol        = "role_name"
        encryptionClass    = "com.mycompany.service.Encrypt"
        encryptionMethod   = "encrypt"
    />

You can use any className and method name, just make sure you deploy your encryption routine as a '.class' file under %CATALINA_HOME%/server/classes or in a JAR file under %CATALINA_HOME%/server/lib

The only pre-requisite for the encryption method is that is must have a signature that matches either
public String xxx(String password)
or
public String xxx(String password, String Userid)

The realm will first look for a method with the single input field, and use if found. If not found it looks for the one with the two input paramters, and use that. If niether method is found, you will get an exception, and a message in the log file.

The reason for the second methods, is in case you want to use their user id as part of the key for the encryption. If not you can just use the single parameter method.

NOTE: if you class needs other relateds classes or jar files make sure they are also deployed in a location visible to tomcat (ie in /server, or /common)

In Later version of Tomcat (aka 4.1.24) it is normal to use the

   <Listener
       className = "org.apache.catalina.mbeans.ServerLifecycleListener"
       debug     = "0"
   />

If this is the case, to avoid a warning on startup, you must point this listener to a definition of any MBeans, in this case if you are using JDBCEncryptionRealm, you need a MBean definition of this.

From release v1.2.0 on-wards of jaffa-tomcat.jar, this file has been included. To reference it from server.xml you can use the following

   <Listener
       className   = "org.apache.catalina.mbeans.ServerLifecycleListener"
       debug       = "0"
       descriptors = "/org/jaffa/tomcat/realm/mbeans-descriptors.xml"
   />