It is common that developers reinvent the wheel when implementing authentication and authorization. The process is not so simple and often leads to security holes.  Fortunately, the Java Servlet Specification - since its earlier versions - defines a way in which access to web resources can be restricted through authorization.  Although there is no standard way to validate the identity of a user, a Servlet container implementation is free to provide any specific mechanisms. In this article we will see how to setup an automatic authorization and authentication with Tomcat 5 or JWSDP 1.3.

For this article assume the following scenario:  Tomcat 5 will be used to deploy a web application 'mywebapp'.  We want to restrict the access to a section under the URL /mywebapp/admin/*. We also want to authenticate the users under an SSL connection, assuming SSL is already setup. We have a database called 'mydb' in a MySql in the same server as Tomcat. The usernames are stored under a table called 'user-table' and the roles under a table called 'user-role-table'. We have two accepted roles for our protected realm: 'administrator' and 'other-role'. We have a custom login and error page that we want to act as the first stage of our application. To set up the authentication and authorization it is divided in two parts; one that is applicable to any Java Servlet container, and other that is only applicable to Tomcat and JWSDP server.

J2EE Standard:
The entire standard configuration is done in the web.xml of the target web application. You have to specify the context-relative URL realm of the resource to be protected as well as the HTTP methods to which the restriction applies. You also have to write the specific roles that will have permission to access the protected resource. In order to use SSL to protect authentication we must specify a transport guarantee for the data.  The Java Servlet specification mentions three types of transport guarantees: Confidential, Integral and None. Both confidential and integral enable SSL.

The roles declared here must match exactly the role we have in our database and the roles that are referenced later in the XML file.
Lets take a look at a part of the web.xml: 

Download the code above

To use your own login an error page we have to setup a login configuration in the web.xml as well. There are four authentication modes supported by the Java Servlet specification:

• The FORM authentication provides no transport protection per se but you can use your own custom defined user interface.                     
• The BASIC authentication provides no transport protection and the user interface used is browser specific. The password is encoded using Base-64 encoding.                     
• The DIGEST is very similar to BASIC, except it protects the password through encryption.                     
• The CLIENT-CERT uses PKI and SSL.  It is by far the most secure of the authentication forms. A user must provide X509 certificate to authenticate with the server.

We will use the FORM-based authentication since we want to provide our own user interface. To overcome the fact that no protection is offered, in the previous XML excerpt we declared that SSL is necessary for this URL realm.

Download the code above

You have to create an HTML page or JSP, with the name you specified under the form-login-page tag that contains a form with the following requirements:

• Data must be posted to a special resource named  'j_security_check'.                     
• The username field must be named  'j_username'                     
• The password field must be named 'j_password'
  An example form will look something like this:
  

Download the code above

Tomcat Specific:
In Tomcat and JWSDP the default authentication mechanism is to check against an XML user database found in the %TOMCAT%/conf/tomcat-users.xml file.  It can also be configured to authenticate with Tomcat realms:

• A database - Uses a JDBC driver to lookup the authentication information.
  className="org.apache.catalina.realm.JDBCRealm"                     
• A DataSource - Can use any DataSource (database connection pooling) to look up the authentication information.  Unfortunately, at this moment there is a bug that impedes interoperation with any Tomcat context DataSource.
  className="org.apache.catalina.realm.DataSourceRealm?                     
• A JNDI source - Uses any JNDI provider to lookup the authentication information.
  className="org.apache.catalina.realm.JNDIRealm?                     
• A JAAS interface - Uses the JAAS framework to authenticate users.
  className="org.apache.catalina.realm.JAASRealm?

Here is a review of the database authentication. Each Tomcat realm is implemented by a particular class. The JDBCRealm class implements a database Realm.  A realm can be configured at the host or context level. It is configured in the conf/server.xml file and, depending on where it is placed, it affects the context or host level. This is an example of a context level configuration with MySQL. Lets take a look at a part of a server.xml

Download the code above

There are a few important parameters in addition to the ones related to the database connection. The userTable attribute names a table that should contain at least two fields, one referred to by userNameCol and other referred to by userCredCol which will be compared against the user supplied username and password respectively. With the configuration above, the realm expects the password to be in clear text.  The attribute userRoleTable names a table that should contain at least two fields, one referred to by userNameCol and other referred to by roleNameCol, which will be used to retrieve the roles of an authenticated user.It is valid for a user to have several roles, but at least one must match exactly a configured role on the web.xml file so authorization is granted to access a protected realm.

More information on Realms and authorization can be found at: http://jakarta.apache.org/tomcat/tomcat-5.0-doc/realm-howto.html

Remember that in order to use a JDBC driver (for example, MySql driver: mysql-connector-java-3.0.9-stable-bin.jar), the JAR file must be visible to Tomcat during startup, so place it either in %TOMCAT%/common/lib or %TOMCAT%/server/lib directories, depending whether the driver is shared with a web application or used only by the Tomcat engine.  The database authentication mechanism can be easily configured to validate against password hashes instead of clear text passwords. When you combine authentication and authorization with SSL and secure software engineering practices you can improve the overall security of your product without spending too much effort on implementing custom solutions.