Security Realms

A security realm is a mechanism for protecting Web application resources. It gives you the ability to protect a resource with a defined security constraint and then define the user roles that can access the protected resource.

Tomcat contains this type of realm functionality as a built-in feature, and the org.apache.catalina.Realm interface is the component that provides this functionality.

The interface provides a mechanism by which a collection of usernames, passwords, and their associated roles can be integrated into Tomcat.

If you downloaded the Tomcat source, you can find this interface in the following location:

<TOMCAT_HOME>/src/catalina/src/share/org/apache/catalina/Realm.java

Tomcat 4, Tomcat 5 & Tomcat 6 provides two classes of Realm implementations: MemoryRealm and JDBCRealm. We discuss each implementation in the following sections.

Memory Realms

The first Realm implementation provided with Tomcat is a memory realm, which is
implemented by the org.apache.catalina.realm.MemoryRealm class. The MemoryRealm class uses a simple XML file as a container of users. The following code snippet contains an example memory realm XML file:

<!--
NOTE: By default, no user is included in the "manager" role required
to operate the "/manager" web application. If you wish to use this app,
you must define such a user - the username and password are arbitrary.
-->

<tomcat-users>
<user name="tomcat" password="tomcat" roles="tomcat" />
<user name="role2" password="tomcat" roles="role2" />
<user name="both" password="tomcat" roles="tomcat,role2" />
<user name="bob" password="changeme" roles="manager" />
</tomcat-users>

As you can see, this file contains nothing terribly complicated. It has a root element of <tomcat-users>, which contains n-number of the sub-element <user>. The <user> element contains all of the necessary information to validate a user. This information is contained in the attributes of the <user> sub-element.

Protecting a Resource with a MemoryRealm

To actually see how a MemoryRealm works, let's create a realm that protects our /thetest application. The steps involved in setting up a new MemoryRealm are as follows:

1) Open the <TOMCAT_HOME>/conf/server.xml and make sure that the following line is not commented out.

2) <Realm className="org.apache.catalina.realm.MemoryRealm" />

By ensuring that this <Realm> entry is not commented out, you are making the MemoryRealm the default realm implementation for the entire default container.

3) Open the <TOMCAT_HOME>/webapps/thetest/WEB-INF/web.xml file and add the
following security constraint as the last sub-element of <web-app>:

4) <!-- Define a Security Constraint on this Application -->

5) <security-constraint>

6) <web-resource-collection>

7) <web-resource-name>TheTest Application</web-resource-name>

8) <url-pattern>/*</url-pattern>

9) </web-resource-collection>

10) <auth-constraint>

11) <role-name>testuser</role-name>

12) </auth-constraint>

13) </security-constraint>

14) You need to focus on only two sub-elements: <url-pattern> and <role-name>. The <url-pattern> sub-element defines the URL pattern that is to be protected by the resource.

The entry that you include protects the entire /thetest Web application. The second sub-element, <role-name>, defines the user role that can access the resource protected by the previously defined <url-pattern>. In summary, this entire entry states that the /thetest Web application can be accessed only by users with a defined role of thetestuser.

15) Add the following <login-config> sub-element directly after the <securityconstraint>.

16) <!-- Define the Login Configuration for this Application -->

17) <login-config>

18) <auth-method>BASIC</auth-method>

19) <realm-name>thetest Application</realm-name>

20) </login-config>
The <login-config> sub-element simply defines the authentication method for the
defined realm. The possible values are BASIC, DIGEST, and FORM.

21) Open the <TOMCAT_ROOT>/conf/tomcat-users.xml file and add the following
<user> sub-element:

22) <user name="robert" password="password" roles="thetestuser" />
The <user> sub-element you are adding creates a new user in the MemoryRealm
database with a name of robert, a password of password, and a role of
thetestuser.

You should notice that the value of the roles attribute matches the
value of the <role-name> sub-element of the previously defined <sercuritycontstraint>.

23) To complete this configuration, stop and restart the Tomcat server.
Now let's actually look at how your newly defined realm affects the /thetest Web
application. Point your browser to the following URL: http://localhost:8080/thetest/login.jsp

If everything went according to plan, you should see a dialog box. Go ahead and enter robert for the username and password for the password, and click on OK.

Again, if everything goes according to plan, you should see the login page of the
/thetest Web application.

You now have a Web application that is protected by a security realm that uses the basic authentication method to authenticate its users.

(c) Copyright 2003 Oxxus Tomcat Hosting Services. All rights reserved