Tomcat 4 Web Agent

Cams agents are integrated with web and application servers to protect resources that the servers provide. When a user's web browser makes a request to a web or application server, the Cams web agent asks a Cams server is access is granted or denied. The web agent enforces the response, including prompting for user authentication if required.

This document provides instructions on how to install and configure the Cams Tomcat 4 web agent. The Cams Tomcat 4 web agent is a Tomcat version 4.x valve and realm implementation. Also, the Cams ServletFilter web agent can also be used with Tomcat 4.

NOTE: For known issues with the Cams Tomcat 4 web agent, see ReleaseNotes.html found in the root directory of the Cams Tomcat 4 web agent distribution.

Installation

These instructions guide you through the installation of Cams Tomcat 4 web agent on a system with Tomcat already installed. If Tomcat is not yet installed, you must first do so. You must also download the Cams Tomcat 4 web agent by logging into the Cams User Portal.

You must unpack the download (cams-webagent-tomcat-1_2-0.tar.gz or cams-webagent-tomcat-1_2-0.zip) into a temporary directory, then copy Cams directories and files to your Tomcat installation tree. In the instructions that follow, environment variable CATALINA_HOME corresponds to your Tomcat 4.X installation home directory.

NOTE: The Cams Tomcat 4 web agent distribution extracts into a version-specific directory tree. So, extracting to directory: /tmp would result in a tree of files like: /tmp/cams-webagent-tomcat-1_2-0/...

Step 1: Extract the Cams Tomcat 4 web agent Files

Linux/UNIX

cd /tmp
tar xvfz cams-webagent-tomcat-1_2-0.tar

Windows

cd C:\temp
pkunzip cams-webagent-tomcat-1_2-0.zip

Change directories to the cams-webagent-tomcat-1_2-0 directory (or whatever directory was created). Files like those shown in Figure 1 should have been extracted.

<!-- Cams Tomcat 4 web agent documentation and license -->
docs/README.txt
docs/LICENSE
docs/ReleaseNotes.html
docs/webagent/*

<!-- Cams Tomcat 4.1 patch files -->
cams/4.1/server/classes/org/apache/catalina/mbean/mbeans-descriptor.xml

<!-- Cams Tomcat 4 web agent configuration file and sample Tomcat server.xml -->
conf/cams-webagent.conf
conf/cams-tomcat-server.xml

<!-- Cams Tomcat 4 web agent Java libraries -->
server/lib/cams-common.jar
server/lib/cams-webagent-tomcat4.jar
server/lib/cams.jar
server/lib/cscore.jar
server/lib/infinitemonkey.dll
server/lib/InfiniteMonkey.jar
server/lib/InfiniteMonkeyLicense.txt
server/lib/log4j.jar

<!-- Cams Tomcat 4 web agent denied, error, and login pages -->
webapps/cams/cams-webagent-test.jsp
webapps/cams/denied.jsp
webapps/cams/error.jsp
webapps/cams/login.jsp
webapps/cams/secured-by-cams.gif
webapps/cams/WEB-INF/web.xml

Step 2: Copy Cams Tomcat 4 web agent Files to CATALINA_HOME

Linux/UNIX

cd cams-webagent-tomcat-1_2-0
cp -r conf $CATALINA_HOME
cp -r server $CATALINA_HOME
cp -r webapps $CATALINA_HOME

Windows

cd cams-webagent-tomcat-1_2-0
xcopy conf %CATALINA_HOME%
xcopy server %CATALINA_HOME%
xcopy webapps %CATALINA_HOME%

WARNING: If using JDK 1.3.x you must configure a cryptography provider for your JRE. The Java Cryptography Extension(JCE) 1.2.x should be installed. To configure a JCE provider open the Java security file JRE_HOME/lib/security/java.security and add the following line:

security.provider.n=com.sun.crypto.provider.SunJCE

Where n is the order in which the providers are looked up (e.g., 1, 2, 3).

Tomcat 4.1.x Issues

Release 4.1.x of Tomcat introduces the use of Java JMX MBeans (MBeans) in the new administrator application. To support the Tomcat 4.1.x administrator application, MBeans support is enabled by default in Tomcat's server.xml configuration file. If you start Tomcat 4.1.x after installing Cams, exceptions will be thrown with the default configuration. You have two options. Option 1 is to disable MBeans support in server.xml (and thereby disable the administrator webapp) by commenting out the corresponding entries as shown in Figure 2.

<!-- Comment out these entries to disable JMX MBeans support 
<Listener className="org.apache.catalina.mbeans.ServerLifecycleListener"
          debug="0"/>
<Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"
          debug="0"/>
-->

Option 2 is to modify Tomcat's mbeans-descriptor.xml file to reference the Cams Tomcat web agent and realm. The original Tomcat 4 mbeans-descriptor.xml file is found in server/lib/catalina.jar. You DO NOT need to remove it. If Tomcat 4 finds server/lib/classes/org/apache/catalina/mbeans/mbeans-destriptor.xml first, it will be used instead. The Cams Tomcat web agent includes a version of mbeans-descriptor.xml with the required modification. To use it, enter:

Linux/UNIX

cd cams-webagent-tomcat-1_2-0
cp -r cams/4.1/server/classes/ $CATALINA_HOME/server/classes/

Windows

CD cams-webagent-tomcat-1_2-0
xcopy cams\4.1\server\classes\ %CATALINA_HOME%\server\classes\

The modified version contains the descriptors shown in Figure 3. You can alternatively insert these descriptors yourself into mbeans-descriptor.xml.

...

<mbean    name="CamsRealm"
     className="org.apache.catalina.mbeans.ClassNameMBean"
   description="Cams implementation of valid users, passwords, and roles"
        domain="Catalina"
         group="Realm"
         type="com.cafesoft.security.webagent.tomcat4.CamsRealm">

  <attribute name="className"
      description="Fully qualified class name of the managed object"
             type="java.lang.String"
        writeable="false"/>

  <attribute name="debug"
      description="The debugging detail level for this component"
             type="int"/>

</mbean>

<mbean   name="CamsTomcatWebAgent"
    className="org.apache.catalina.mbeans.ClassNameMBean"
  description="Valve that performs access control, authentication,  				
               session access, and session control"
       domain="Catalina"
        group="Valve"
         type="com.cafesoft.security.webagent.tomcat4.CamsTomcatWebAgent">

 <attribute name="className"
     description="Fully qualified class name of the managed object"
            type="java.lang.String"
       writeable="false"/>

 <attribute name="debug"
     description="The debugging detail level for this component"
            type="int"/>

</mbean>

...

Using these descriptors eliminate the exceptions thrown at Tomcat startup, however, they do not enable the Cams Tomcat 4 web agent and realm to be managed by the Tomcat administrator webapp.

NOTE: Testing has been performed against Tomcat 4.1.12, 4.1.18, and 4.1.24.

Web Agent Configuration

The Cams Tomcat 4 web agent is configured in cams-webagent.conf. In addition, you also need to edit the Tomcat server.xml file and integrate the Cams login, error, and denied pages.

NOTE: To secure resources on your Tomcat server, you'll also need to configure a Cams security domain. See the Cams Server Configuration section in this document for more information.

Editing cams-webagent.conf

Open the cams-webagent.conf file in a text editor. The file contains comments to help you understand the property values that you may need to change, as shown in Table 1.

Table 1 - Values you may need to edit in cams-webagent.conf

The other properties in this file configure debug and the Cams message protocol. You should not change the message protocol values unless instructed to do so by Cafésoft support.

Editing server.xml

You are now ready to edit Tomcat's server.xml. Before making changes, you should backup your existing server.xml.

You can copy conf/cams-tomcat-server.xml to conf/server.xml. In this case, you should not have to edit server.xml and can skip to the next section.

To use an existing server.xml file you must insert the tags that invoke the Cams Tomcat agent and remove or comment-out any potential conflicts. First, the following text should be inserted within the <engine> block of the service to be protected (typically the Tomcat-Standalone service):

<Valve className="com.cafesoft.security.webagent.tomcat4.CamsTomcatWebAgent"
configPath="${catalina.home}/conf/cams-webagent.conf"
contextClass="com.cafesoft.security.common.agent.StandardCamsAgentContext"/>

If you plan to use J2EE Servlet security API's (see the Cams Programmer's Guide - Webapp Programming) then you will additionally need to insert the Cams Tomcat realm. The following text should be inserted directly below the Cams Tomcat agent.

<Realm className="com.cafesoft.security.webagent.tomcat4.CamsRealm"/>

See CATALINA_HOME/conf/cams-tomcat-server.xml for an example. Any conflicting Tomcat container security should be removed or commented out. For example, by default, the Tomcat-Standalone service ships with the MemoryRealm enabled. Comment-out the MemoryRealm by placing the XML closing comment tag after the Realm tag:

<!-- Because this Realm is here, an instance will be shared globally
<Realm className="org.apache.catalina.realm.MemoryRealm" />
-->

The Cams Tomcat 4 web agent is implemented as a Tomcat valve that must be inserted into the engine request pipeline for each service it protects. You may need multiple insertions if your Tomcat installation uses multiple services and engines. For example, Tomcat ships with the Tomcat-Standalone and Tomcat-Apache services. To use both, you would remove or comment-out the MemoryRealm in both services and add the Cams Tomcat 4 web agent valve and realm to each.

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Tomcat 4 web agent installation. An self-documented test page is provided with the cams webapp that you can use for testing.

WARNING: You may have enabled other Tomcat security realms such as a JDBCRealm or LDAPRealm. To avoid security policy conflict, you should remove native Tomcat security from resources protected by Cams. Also, you should remove all container level security tags from each webapp's web.xml descriptor file.

Securing Directories and Files

If you have not done so already, you should secure important Tomcat configuration and log directories. They may contain Tomcat SSL certificates, configuration files containing passwords or secret keys, and log files containing sensitive information.

In a typical production environment, the Tomcat server is started and executed by the administrative root user (Unix) or Administrator user (Windows NT/2000/2003). The general strategy for securing Cams-related configuration files and directories is to:

1. Ensure that the Tomcat server is executed as the appropriate administrative user (root or Administrator), hereafter referred to as the owner. This enables the Cams Tomcat 4 web agent to run within the secured file and directory environment described below.
2. Enable owner read/write/execute permissions on all directoris containing Cams files, but no permissions for all other users and groups. This enables owner processes to scan and modify the contents of directories, while prohibiting all other users and groups from seeing or modifying the contents of these directories.
3. Enable owner read/write permissions on configuration files and log files, but no permissions for all other users and groups. This ensures that an arbitrary user cannot replace, overwrite, or redirect log files to obscure security violations or obtain sensitive information via trace logs.

The following sections provide operating system-specific instructions for securing Cams web agent files and directories in the Tomcat environment.

Linux/UNIX Directories and Files

In the instructions that follow, it is assumed that the Tomcat server is executed by root on your Linux/UNIX system. For the sake of this example, assume that:

1. Tomcat is installed at /usr/local/jakarta-tomcat, hereafter referred to as CATALINA_HOME
2. The Tomcat configuration directory is at CATALINA_HOME/conf
3. The Tomcat logs directory is at CATALINA_HOME/logs
4. That you are logged in as root

As is the case with any command that root executes, you must take care that it is protected from modification by non-root users. Not only must the files themselves be writable only by root, but so must the directories, and parents of all directories. It is assumed that /, /usr, and /usr/local are only modifiable by root. When you install the Tomcat server, you should ensure that it is similarly protected.

The following steps can help you protect sensitive information stored in Cams Tomcat 4 web agent configuration and/or log files.

Step 1 - Change directories to the Tomcat installation directory

cd /user/local/jakarta-tomcat

Step 2 - Set user and group ownership for the conf and logs directories

chown root.root conf conf/cams-webagent.conf
chown root.root logs logs/*

This command sets user and group ownership to root for the specified directories and files.

Step 3 - Set file and directory permissions

chmod 700 conf logs
chmod 600 conf/cams-webagent.conf logs/*

The first command sets read/write/execute permissions that enable only owner access to the conf and logs directories. The second command sets read/write permission for the owner of the cams-webagent.conf file and log files. No other users or groups are given any permissions.

Windows Directories and Files

In the instructions that follow, it is assumed that the Tomcat server is executed by Administrator on your Windows NT/2000/2003 system. For the sake of this example, assume that:

1. Tomcat is installed at C:\jakarta-tomcat, hereafter referred to as CATALINA_HOME
2. The Tomcat configuration directory is at CATALINA_HOME\conf
3. The Tomcat logs directory is at CATALINA_HOME\logs
4. You are logged in as Admininistrator to your Windows NT/2000/2003 server or domain controller

As is the case with any command that Admin executes, you must take care that it is protected from modification by non-Admin users. Use the following steps to secure Cams Tomncat webagent-related directories and files:

Step 1 - Set user and group ownership of all files and directories

This is done using the Windows NT/2000/2003 graphical user interface.

1. Using the Windows Explorer file browser, select the top-level Tomcat installation directory: C:\jakarta-tomcat
2. Right click on the folder and select Properties from the pop-up menu
3. In the dialog box that appears, select the Security tab
4. Click on the Ownership button
5. In the dialog box that appear, confirm that Administrators is the intended owner, then click Take Ownership

Step 2 - Set all directory and file permissions

From the same Security tab in the context-sensitive dialog box for directory C:\jakarta-tomcat used in Step 1:

1. Click on the Permissions button
2. In the Directory Permissions dialog box that appears, confirm that the directory Owner is Administrators
3. Select check box Replace Permissions on Subdirectories (e.g., make sure it is checked)
4. Select check box Replace Permissions on Existing Files (e.g., make sure it is checked)
5. In the list of all User\Group items listed, Remove all items except Administrator
6. Select the list item Administrator, then select Type of Access = Full Control

Java Server Pages

The distribution cams directory includes four sample Java Server Pages (JSP):

• cams-webagent-test.jsp - enables lazy and proactive authentication and access control testing, displays context sensitive information for authenticated users
• denied.jsp - displays an access denied page if access to a resource request is denied
• error.jsp - displays an error page if an authentication or resource request error occurs
• login.jsp - displays a login page if a protected resource request is made and the user's identity is not known

cams-webapp-test.jsp

You should browse to cams-webagent-test.jsp to understand how to configure and use it for testing. The page is posted to the URI specified by the cams.login.uri property in cams-webagent.conf along with the following form name/value pairs:

• cams_cb_username - the username
• cams_cb_password - the user password
• cams_security_domain - the login security domain
• cams_login_config - the security domain's login-config-entry to use
• cams_original_url - The URL to redirect to after successful authentication and authorization

When you click the submit button, the Cams Tomcat 4 web agent intercepts the POST to the cams.login.uri and sends the request to the Cams server. The request includes the security domain and a login-config-entry, which the Cams servers will use to attempt login. If you successfully authenticate and are authorized (depending upon how you configure the security domain), the browser is redirected to the cams_orginal_url and user specific information is displayed by cams-webagent-test.jsp.

login.jsp

When you request a protected resource that requires authentication and Cams doesn't know your user identity, the Cams Tomcat 4 web agent displays a login page as specified by the login-parameters in a security domain's login-config.xml file. The login page is identical to index.jsp, except that the hidden values are dynamically populated as shown in Example 1.

WARNING: You must correctly configure the login-parameters in the security domain's login-config.xml file or the login page will not be displayed. See the Cams Administrator's Guide - Login Configuration for more information on configuring login-parameters in login-config.xml.

<!-- Populate hidden fields from their request parameters -->
<input type="hidden" name="cams_security_domain" 
                    value="<%= request.getParameter("securityDomain") %>">
<input type="hidden" name="cams_login_config"    
                    value="<%= request.getParameter("loginConfig") %>">
<input type="hidden" name="cams_original_url"
                    value="<%= request.getParameter("originalUrl") %>">

The difference between cams-webagent-test.jsp and login.jsp are that you arrive at the former lazy authentication login page after requesting a resource for which your identity is unknown to the Cams server. Because of the resource request, Cams knows the security domain and login-config-entry to which the resource belongs (and, of course, the original URL).

denied.jsp

If you are denied access to a resource by Cams, the page specified by the cams.denied.url property in cams-webagent.conf is displayed. Example 2 shows a script that displays dynamic messages.

<!-- Display any dynamic access denied messages -->
<%
			
	String message = null;
			
	message = request.getParameter("message");
	if(message != null)
	{
%>

 <p class=error><%= message %></p>

<%
	} 
%>

error.jsp

If an error occurs, Cams displays the page specified by the cams.error.url property in cams-webagent.conf. Example 3 shows a script that displays dynamic messages.

<!-- Display any dynamic error messages -->
<%
			
	String message = null;	
	message = request.getParameter("message");
	if (message != null)
	{
%>

 <p class="error"><%= message %></p>

<%
	} 
%>

NOTE: In order to ensure that the browser does not cache these pages, it is important that you use the following HTML Meta tags in the HEAD section of each page:

<meta http-equiv="Pragma"        content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">   		
<meta http-equiv="Expires"       content="-1">

Optimizations

The Cams Tomcat 4 web agent installs with default configuration properties. However, you may find it beneficial to configure your installation to more adequately meet the requirements of your environment. See the following documentation regarding available Cams web agent optimizations: Cams Web Agent Optimizations.

Cams Server Configuration

Before you start the Tomcat server with a Cams Tomcat 4 web agent, you'll need to ensure that the Cams server knows about it. See the following documentation, which explains Cams server configuration requirements for each web/application server and Cams agent: Web Agent-specific Cams Server Configuration.

Testing

That's it, you should now be able to start Tomcat to test your Cams Tomcat 4 web agent configuration. After you've started both Tomcat with the Cams Tomcat 4 web agent and the Cams server, test the configuration using:

http://[hostname:port]/cams/cams-webagent-test.jsp

Login to an account in the security domain that you've established. See the test page for more configuration and testing information.

Back | Next | Contents

© Copyright 1996-2003 Cafésoft LLC. All rights reserved.