Security Realms in Tomcat

Security means different things to different people, but
everyone agrees that there is a need to control access so that only authorized
users can access the resources. Java EE applications consist of components that
can contain both protected and unprotected resources. Often, you need to protect
resources to ensure that only authorized users have access. On the Web, security
boils down to four major issues namely authentication, authorization,
confidentiality and integrity. In a series of two articles we'll first explore
security realms in Tomcat and then dive into SSL configuration and explore
programmatic security.

Security in Java EE Web tier

The Java EE specification follows a declarative mechanism for defining
security to constrained resources in a Web application. Declarative security
expresses an applications security structure, including security roles, access
control and authentication requirements, in a form external to the application.
This is often referred to as role-based security configuration.

Servlets use role-based authentication and authorization to
manage access. A role is a definition of the way a user will use the system.
It's an abstract logical grouping of users who have similar responsibilities.
Some roles include user, administrator, manager and so on. The Java EE
specification prescribes a model that separates the application developer from
the application deployer.

Security in Java EE Web applications adopts this model
where developers have very little to worry about security. A major part of
security configuration is carried out at deployment time. Security in Java EE
applies to all the tiers of an enterprise application. It is also applicable to
JVM and EJB calls, but currently we restrict ourselves to security issues in the
Web tier, which is implemented in the servlet container.

When access is restricted to a resource, Tomcat server causes an automatic authentication request to the remote browser

Security realms

A security realm is a collection of users and groups that are controlled by
an authentication policy. It's a mechanism used for protecting Web application
resources. A security realm is merely a place where authentication information
(username, password and their groups) is stored. For developers, a security
realm is merely a container specific implementation of Realm interface. Tomcat
ships with two out-of-the-box security realms, namely memory realm and JDBC
realm. Let us now explore these security realms.

Memory realms

A realm is a place where authentication information is stored. In its
simplest form, a realm is a list of user names, passwords and roles. In Tomcat,
you can use an XML file called 'tomcat-users.xml', located in %CATALINA_HOME%\conf
directory, which holds name-password-role sets that the container uses to
authenticate app users as shown below.

 

 

 

  password="secret" roles="admin "/>

  password="secret" roles="manager "/>

  password="secret" roles="guest"/>

The 'name' attribute has a string representing the
username that will be used in the login form. The 'password' attribute
contains a string representing the password that will be used to gain access to
protected resources. Finally, the 'roles' attribute contains the role/roles
assigned to the named user. If a user belongs to more than one role, the value
of the role attribute must contain a comma-separated list of roles. That
'tomcat-users.xml' file applies to all applications deployed under Web
applications. It's known as the memory realm because Tomcat reads this file
into memory at start-up time. The tag is used in defining security
roles. This helps in mapping the roles in vendor specific 'users' file to
the roles in the DD (Deployment Descriptor) 'web.xml' file (shown later).
Please note that any changes made to this file require a restart.

When the authentication is successful, the execution continues and our users will see this page

JDBC realms
 

A JDBC security realm class is much like the memory realm,
with the difference of where it stores its collection of users. A JDBC realm
stores all of its users in a user-defined, JDBC-compliant database. We'll use
MySQL for storing user credentials and group information. We will need three
tables-for storing user credentials, for group names and finally, a table
which maintains association between a user and roles, as shown in the following
code.

CREATE TABLE users(
 

user_name varchar(25) NOT NULL,
 

password varchar(25) NOT NULL,
 

PRIMARY KEY(user_name));
 

CREATE TABLE roles(
 

role_name varchar(25) NOT NULL PRIMARY KEY
 

);
 

CREATE TABLE user_roles(
 

user_name varchar(25) not null,
 

role_name varchar(25) not null,
 

PRIMARY KEY(user_name, role_name)
 

);
 

insert into users values('marshal','secret');
 

insert into users values('kunal','secret');
 

insert into users values('james','secret');
 

insert into users values('ramesh','secret');

insert into roles values('manager');
 

insert into roles values('admin');
 

insert into roles values('guest');
 

insert into user_roles values ('marshal','manager');
 

insert into user_roles values ('kunal','admin');
 

insert into user_roles values ('james','guest');
 

insert into user_roles values ('ramesh','guest');

If the authentication fails because of invalid credentials, this page is sent automatically

Configuring JDBC realm in Tomcat
 

Next, we have to fine tune Tomcat to enable JDBC realm. We
need to edit the server.xml file, which resides in the conf directory of your
Tomcat installation (CATALINA_HOME ). But, first the
default MemoryRealm needs to be commented out as follows.

 


 

debug="99" driverName="com.mysql.jdbc.Driver"
 

connectionURL="jdbc:mysql://localhost/secureDB"
connectionName="kunal" 

connectionPassword="java_facier" 

         userTable="users"
 

userNameCol="user_name"  

userCredCol="password" 

userRoleTable="user_roles"  

roleNameCol="role_name"
 

/>

This tag defines a JDBC realm that our
application will use to look up user credentials and map to their roles.
The 'driverName' attribute references the JAR containing the JDBC driver. So
make sure that the required JAR is placed in Tomcat's CLASSPATH. The URL
referencing the database containing the user authentication information is
indicated by 'connectionURL' attribute.  The 'connectionName' and
'connectionPassword' attributes determine the username and password used to
connect to the database. The database table containing the user's information is
indicated by the 'userTable' attribute. The 'userNameCol' attribute
determines the column in the userTable that references the user's username. The
database table containing the mapping between the userTable and the table
containing the possible user roles is determined by 'userRoleTable'
attribute. Finally, the 'roleNameCol' attribute determines the column in the
userRoleTable that contains the roles assigned to a user.

Protecting a constrained resource
 

A Web resource can be protected by specifying a security
constraint. Java EE Web applications use a concept called security constraint to
declare security. It is a declarative way of indicating the required security
for content within a Web application.

A security constraint determines who is authorized to
access a Web-resource collection, which is a list of URL patterns and HTTP
methods that describe a set of resources to be protected. This is how you
declaratively specify that a given resource/method combination is accessible
only by users in certain roles. This is called declarative security because it
is declared in the DD 'web.xml' file. We'll specify security constraint
for our application in this file as:

  

      Example
Security Constraint 

Secure Area 

         /secret/* 

 GET 

POST 

      

       

manager 

admin 

     


 

BASIC
 

 

    

admin

manager 

guest
     

The tag protects a
. The purpose of
sub-element is to tell the container which resources and HTTP method
combinations should be constrained.

The elements define the resources to be
constrained. The element(s) describe which HTTP methods are
constrained for the resources defined by the element. The
element lists which roles can invoke the constrained
HTTP methods. The element specifies the login methodology
to be used by this Web application. Possible values are BASIC, DIGEST, FORM and
CLIENT-CERT. Except for FORM, once you have declared the
element in the DD, the container takes care of everything, automatically
requesting a username and password when a constrained resource is requested and
you don't have to take any extra efforts.

Under the hood
 

All that said, when the server receives a request for a
protected resource, the server looks for a principal object (name of a user
within the authentication realm) stored in the users HttpSession object. If the
server locates a Principal, the roles of the Principal are compared to those
required to access the resource. The user is granted access only if the
Principal belongs to the required role and username and password are matched.

 If the server cannot locate the principal or if the
principal does not belong to any of the allowed roles, the clients browser
window pops up a login box (figure 1), only if the username and password are
valid and belongs to a Principal in an allowed role for the originally requested
resource, access is granted (figure 2). In any other case, the server displays
an invalid login error message (figure 3).

Conclusion
 

Developing secure applications and protecting data are
priorities in today's environment. Role-based access to Web pages is based on
URL pattern matching. Roles can be authorized to access a specific web page (a
static page, a servlet, or an EJB). By using Web page URL mappings in the
deployment descriptor, the physical Web pages can be grouped together under
logically similar names to simplify security authorization. In the next article,
we'll learn how to fine tune Tomcat for SSL to send data over the network with
integrity and confidentiality.

Kunal Jaggi