User authentication is perhaps one of the most critical
requirements of any Web application and is often taken for granted.
While designing any Web applications, quite a bit of thought needs to
be provided to this process of ensuring that the identity of the end
user is validated before the user is allowed to perform any operations
on the site.
While various techniques for user authentication exist (e.g.
password-based, token-based, digital certificate-based, using
biometrics, etc), often the concept of the Secure Socket Layer (SSL)
comes into picture. While we will discuss SSL in great detail in a
future article, the focus of this article is how to set it all up in
the most commonly used Web server, Tomcat. In other words, most of us
would know that SSL secures traffic between the Web browser and the Web
server. How SSL achieves it is not the focus of this article. Rather,
assuming that SSL does it somehow (to be discussed in a separate
article), this time we will see how Tomcat can make use of SSL in
This article describes the steps needed in making user authentication
secure in Tomcat. This assumes that Tomcat is installed under a
directory named tomcat on the C drive of the computer.
Step 1: Edit tomcat-users.xml file
basic premise for user authentication in Tomcat is the tomcat-users.xml
file. This file can be located under our tomcat installation at the
path c:tomcatconf. This file specifies the names of the users that
can access the Web pages running on Tomcat, and the roles that they are
mapped to. As a simple example, suppose that my user name is atul, and
I have been assigned a role of manager. Then, the tomcat-users.xml file
should have the following entries for me.
<?xml version=’1.0′ encoding=’utf-8’?>
<user username=”atul” password=”atul” roles=”manager”
The significance of this would become clear shortly. For now,
we will take this for granted.
Step 2: Create a Digital Certificate to be used for SSL enabling in
To enable SSL on Tomcat, the basic requirement is to create a digital
certificate. To put it very simplistically, a digital certificate binds
a person or an organization to a unique public key, just as a passport
binds a person to a unique passport number. For the purpose of creating
a digital certificate in Tomcat, we need to use the free utility that
ships with the JDK, called as Keytool. It can be invoked on the command
prompt, as follows:
keytool –genkey –alias atul
This is informing the keyool utility that we want to create a
keystore file, which encapsulates a digital certificate that can be
used for SSL connectivity. Keytool asks for details such as name,
organization, city, etc, which can be provided at the prompt. It would
also ask a password for storing and later retrieving these details. We
can provide a password of our choice, but need to remember it. A sample
screen is shown below.
If everything is ok, this would have created a file with extension
.keystore in the directory where the command prompt was invoked. This
file internally contains the digital certificate that Tomcat would
Step 3: Add the security-constraint element to the web.xml file
The next step needed is to create a security-constraint element in the web.xml file to
indicate which resources need to be protected by using SSL. In other
words, here we are saying that particular JSPs, servlets, etc demand
that the user authenticate herself before attempting to access them.
The web.xml file should have the following entries.
Here, we are saying that for a JSP page titled Test.jsp, we
want confidential communication using SSL, and would like all GET or
POST requests to be allowed only for the manager role (defined earlier
in step 1).
PAGE 1 OF 2
Step 4: Enable SSL connections via the web.xml file
The last step signifies that we want to enable SSL connections on our
Tomcat installation. For this purpose, in the same web.xml file, add
the following (or uncomment, if already present).
This specifies that port 8443 should be opened for receiving
TLS requests (TLS is a modified version of the SSL protocol) using the
https method, instead of the traditional http.
Provided we have done everything specified earlier correctly, our job
is done! Now, restart Tomcat, open browser, and type the appropriate
URL for Test.jsp. This should redirect our request to port 8443, and
show us the following screen.
Click on OK. It should display the following screen.
We can view the certificate details by clicking on the said button
above. This will show us the details of the certificate the way we had
provided earlier. If we click on OK, the following screen appears.
This proves that we are being asked for the user id and password (i.e.
authentication is enabled) and also that SSL is being used (from the
URL mentioned in the above screen).
If we provide the right user id and password (as specified in step 1
earlier), we would be allowed access to Test.jsp. Otherwise, we would
be told that authentication has failed.
That is all that takes us to enable secure user id-password based and
SSL-enabled authentication in Tomcat.
Kahate writes about Java Security in this monthly
column on IndicThreads.com. Atul is the author of 13 books including
and Network Security“.
He is currently a Project Manager at i-flex solutions limited, Pune,
India. Atul can be reached at (akahate at gmail
* Call For Speakers! Submit A Talk on Web Technologies, Internet Of Things, Serverside, Cloud or Big Data For The Upcoming
IndicThreads.com Developer Conference, Feb 2015, Pune – India.
Latest posts by Atul Kahate (see all)
- Tableless Web Page Design Using CSS - May 28, 2009
- SSL Is Still The Only Scalable and Rock Solid Payment Protocol Available - December 24, 2008
- The Curious Flaw in DSA Digital Signatures - November 18, 2008