Using Tomcat 4 Security Realms

07/24/2001

In this article, we will

• Define security realms
• Describe Memory Realms
• Describe JDBC Realms

Security Realms

A security realm is a mechanism used 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 has this type of realm functionality built in. The component that provides this functionality is the org.apache.catalina.Realm interface. It provides a mechanism by which a collection of usernames, passwords, and their associated roles can be integrated into Tomcat. If you download the Tomcat source, you will find this interface in the following location:

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

There are two Realm implementations provided in Tomcat 4. We will discuss each of these implementations in the following sections.

Memory Realms

The first Realm implementation provided with Tomcat is a memory realm. The class that defines the memory realm is org.apache.cataline.realm.MemoryRealm. The MemoryRealm class uses a simple XML file as a container of users. The following code snippet contains a sample memory realm XML file:

<tomcat-users>
<user name="tomcat" password="tomcat" roles="tomcat" />
<user name="role1" password="tomcat" roles="role1" />
<user name="both" password="tomcat" roles="tomcat,role1" />
</tomcat-users>

Note: The default location of the MemoryRealms XML file is the <tomcat_home>/conf/tomcat-users.xml. You can change the location of this file by substituting a new relative or absolute path in the pathname attribute of the <realm> element described in the following section.

As you can see, there is nothing terribly complicated about this file. 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. Table 1 contains a description of each of the attributes required in the <user> sub-element.

Table 1. The Attributes of the <user> Sub-Element
Attribute	Description
name	The name attribute contains a string representing the username that will be used in the login form.
password	The password attribute contains a string representing the password that will be used in the login form.
roles	The roles attribute contains the role or roles assigned to the named user. This is the value that must match the <role-name> sub-element of the security constraint defined in the web applications web.xml file. If more than one role is assigned to the user, then the value of the roles attribute must contain a comma-separated list of roles.

Protecting a Resource with a MemoryRealm

To actually see how a MemoryRealm works, let's create a realm that protects a sample web application named /onjava. At this point, if you have not already done so, take a look at my previous OnJava article, Deploying Web Applications to Tomcat. We will be using the /onjava web application from it. The steps involved in setting up a new MemoryRealm are described in the following list.

1. Open <tomcat_home>/conf/server.xml and uncomment the following line.

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

   By un-commenting this <realm> entry, you are making the MemoryRealm the default realm implementation for the entire default container. If you cannot find this entry, add it directly under the Engine sub-element.

2. Open <tomcat_home>/webapps/onjava/WEB-INF/web.xml and add the following security constraint:

   <security-constraint>
    <web-resource-collection>
        <web-resource-name>OnJava Application</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>onjavauser</role-name>
    </auth-constraint>
</security-constraint>

   There are only two sub-elements that you need to focus upon. The first is the <url-pattern> sub-element. This sub-element defines the URL pattern that will be protected by the resource. The entry you included protects the entire /onjava 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 /onjava Web application can only be accessed by users with a defined role of onjavauser.

3. Add the following <login-config> sub-element directly following the <security-constraint>.

   <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>OnJava Application</realm-name>
</login-config>

   The <login-config> sub-element defines the authentication method for the defined realm. The possible values are BASIC, DIGEST, and FORM. And the <realm-name> sub-element names the Web resource that this <login-config> maps to.

4. Open <tomcat_root>/conf/tomcat-users.xml and add the following <user> sub-element:

   <user name="bob" password="password" roles="onjavauser" />

   The <user> sub-element you are adding will create a new user in the MemoryRealm database with a name of bob, a password of password, and a role of onjavauser. You should notice that the value of the roles attribute matches the value of the <role-name> sub-element of the previously-defined <security-contstraint>.

5. To complete this configuration, stop and restart the Tomcat server.

Pages: 1, 2

Next Page