Setting up Secure Web Authentication in Tomcat

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
real-life situations.

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′?>


<role rolename=”manager”/>
<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
–keyalg RSA

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.

Command Prompt

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

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


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

port=”8443″ maxHttpHeaderSize=”8192″

minSpareThreads=”25″ maxSpareThreads=”75″


scheme=”https” secure=”true”

sslProtocol=”TLS” />

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.

Certified by unknown authority

Click on OK. It should display the following screen.

Domain Name Mismatch

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.

Authentication Required

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.

Related –

Returning Arrays or Objects – A Security Problem in Java

Using the Java ByteCode Verifier To Prevent Malicious Access

writes about Java Security in this monthly
column on 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
dot com)

Atul Kahate

Atul Kahate is Head - Technology Practice, Oracle Financial Services Software Limited (formerly i-flex solutions limited). He has authored 20 books on Information Technology, 2 on cricket, and over 2000 articles on both of these in various newspapers/journals. Web: Email at

12 thoughts on “Setting up Secure Web Authentication in Tomcat

  • January 29, 2011 at 3:54 pm

    You can find the web.xml file here provided you have installed Tomcat in your C drive

    C:Tomcat 6.0webappsROOTWEB-INF

  • October 7, 2008 at 12:42 am

    hey, is there another way for authentication in tomcat. e.g. apache authentication htpassword file.

  • September 23, 2008 at 3:08 am

    Step 2 mentions about creating the keystore file. But I could not find out how the keystore is getting linked to the web application. Do we specify the file name in any of the web app property files.

  • July 18, 2008 at 4:02 am

    Hi i could not able to create a keystore file. i am getting Filenotfoundexception. ANy help?

  • May 21, 2008 at 3:08 am

    i have a java programs,oath signature also,herongyang crypto programs etc,how can i use this to sign a file ,how to prepare a software to sign automatically, any familier .com is there please help me,,,,, my email id is

Leave a Reply