Managing Authentication in Tomcat with JDBC Realms

After few times ago, we have used session to managing authorization for accessing Jsp pages, now let’s try to make another authentication for a web application by using Realms.

On Apache or any similar web server, we use Realms authentication by include a file called .htaccess to a directory, so only the listed users can access the content of those directory.

Just like the Apache, Realm is a feature of Tomcat which handles an authentication for the user who would like to access all the resources on a web application. Realm controls the roles of each listed user, these roles are references for tomcat to rule out which users can access which web application. By default Realms is flexibility supported by Tomcat. This flexibility mean is Tomcat is supporting this authentication with several ways that we can use as use as we like. The Realms authentication methods already supported by Tomcat are:

  1. File based authentication (The Memory Realms). With this method, the authentication processed by reading a file called tomcat-users.xml that exist on <Tomcat-Folder>/conf/tomcat-users.xml, this file contains a list of users with their roles.
  2. Database (JDBC) authentication(The JDBC Realms). This method is using database as storage of user list and its roles. On Tomcat 5.5, by default, there’s a few database software which is already supported for this JDBC Realms methods. In order to use this method we have to install the database connector by copying the database connector library such as mysql-connector.jar onto <Tomcat-Folder>/common/lib/.
  3. JNDI authentication (JNDI Realms). On this authentication method, Tomcat will validate user and its roles by reading the web directoryservice, such as LDAP. When using this authentication method the JNDI providers have to installed to Tomcat by copying the libraries on to <Tomcat-Folder>/common/lib/ folder.

From those above Realms authentication, we will try the second method which is Database (JDBC) authentication(The JDBC Realms) as out try-it-out now. We will use mysql database as storage of users list and its roles. While the scenarios of our try-it-out today are bellows:

  • Create a database as a storage which can hold users list and its roles.

  • Create a mysql username and password, this username is dedicated for a database that we have created on first step, and this username only had read privileges.

  • Activate Realm JDBC configuration on Tomcat.

  • Create web application configuration in order to make this web application support Realms.

On above scenarios, actually we only do once from step 1 to step 3, means the configuration from step 1 to step 3 will became permanent on Tomcat environment. While the step 4 is optional, means every web application that we will deploy later is may to use this Realm authentication, and may not use too, so it’s depends on us to decide whether a web application will using Realm authentication or not. And then if we want to add user with its roles, so the modification will only do inside mysql database.

And now let’s run out one by one the scenarios above. For the first scenario, please create a database and its tables on mysql database, just like mysql query bellows:

create database tomcat_server;
use tomcat_server;
-- Table structure for table `user_auth` --
  ( `USERNAME` varchar(30) NOT NULL default '',
  `PASSWORD` varchar(30) NOT NULL default '',
-- Dumping data for table `user_auth` --
INSERT INTO `user_auth` (`USERNAME`, `PASSWORD`) VALUES ('admin', 'admin99'), ('mojo', '7mono7');
-- Table structure for table `user_role` --
  ( `ROLE_NAME` varchar(30) NOT NULL,
    `USERNAME` varchar(30) NOT NULL )
-- Dumping data for table `user_role` --
INSERT INTO `user_role` (`ROLE_NAME`, `USERNAME`) VALUES ('tomcat', 'mojo'), ('manager', 'admin'), ('admin', 'admin');

These Query, can also directly executed by copy-paste onto mysl console, just remember the database, tables, users, and roles for the next configuration or scenarios.

Let’s continue with the 2nd scenario which is creating dedicated mysql username and password which only have read only privileges access. Why read-only privileges access? Because we have to be careful to give an access privileges on database user, especially the context of this Realms is related with the access of our whole web application. For this 2nd scenario, these is only my suggestion, but if you want to make a database user with more access privileges than this scenario for your next development, go a head (All by your own risk). Below is a sample query which can accommodate the 2nd scenario.

grant select on tomcat_server.* to 'tomcat-user'@'localhost' identified by 'tomcat55';

On above query, we make a user named tomcat-user and the password is tomcat55, grant select is a command of mysql database that this user have the read-only access to tomcat_server database.

And then let’s continue to the 3rd scenario, which in this scenario, we will activate the Realm configuration with JDBC methods on Tomcat. Realm configuration placed on servlet.xml file which is located on <Tomcat-Folder>/conf/ folder. So we have to modify this file in order to activate Realm with JDBC method. There are two steps to do in this 2nd scenario. The steps are:

  1. Activate Realm Configuration.

    Find and modify the servlet.xml just like bellow:

    <Realm className="org.apache.catalina.realm.UserDatabaseRealm" 
  2. Activate and modify the JDBC Realm configuration refers to 1st scenario that we did before. Modify the server.xml file just like below:

     <Realm className="org.apache.catalina.realm.JDBCRealm" 
               connectionName="tomcat" connectionPassword="tomcat55" 
               userTable="user_auth" userNameCol="USERNAME" 
               userCredCol="PASSWORD" userRoleTable="user_role" 
               roleNameCol="ROLE_NAME" /> 

    Lets discuss a bit for our review of above configuration, in this configuration we are using com.mysql.jdbc.Driver for mysql-connector driver, and the we are using tomcat as a name for database username and for the database password we are using tomcat55 to create connection into mysql database as we have created before on the previous scenarios. Please make sure that the value on this configuration is correct as we create the data on database at the previous scenario.

And then now we can run 4th scenario which is applying JDBC Realms authentication to our web application. Just create or use the existed web application to applying this Realms authentication. We can apply this Realms Authentication by modifying web.xml file which is located on <Tomcat-Folder>/webapps/<your’s-application>/WEB-INF/ folder.

The modification can be do by adding few lines just like below on our web.xml file:

<?xml version="1.0" encoding="UTF-8"?> 
<web-app xmlns="" 
<!--Access Configuration based on Realms--> 
         <web-resource-name>All Page</web-resource-name> 


On those lines above, all the authentication will be applied to whole resources on this web application, marked by line <url-pattern>/*</url-pattern>, and then for the authorization methods we are using BASIC.

That’s all, our try-it-out, using JDBC Realm on Tomcat as a validation for user to our web application resources. Please don’t you ever have a doubt to more explore for your own need and your own desires.


Menteng, Januari 26th 2008.



6 thoughts on “Managing Authentication in Tomcat with JDBC Realms

  1. Pingback: Managing Authentication in Tomcat with JDBC Realms | XML Developer

  2. Hi,

    thank you very much for sharing this very nice example!

    One little correction:

    This does not work:
    <Realm className="org.apache.catalina.Realm.JDBCRealm"

    This works:
    <Realm className="org.apache.catalina.realm.JDBCRealm"

    With a small "r" in realm.

    M Zach

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s