Cams Web Agent Guide

Tomcat 7 Web Agent Integration

Cams web agents are integrated into web and application servers to protect the resources that they provide. When a user's web browser makes a request to a web or application server, the Cams web agent asks a Cams policy server if access is granted or denied. The Cams 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 7 web agent. The Cams Tomcat 7 web agent is a Tomcat version 7.x valve and realm implementation.

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

Installation

These instructions guide you through the installation of Cams Tomcat 7 web agent on a system with Tomcat already installed. If Tomcat 7 is not yet installed, you must first do so. You must also download the Cams Tomcat 7 web agent. If you are not a currently registered customer or evaluator, you will also need to request an evaluation license.

You must unpack the download (cams-webagent-tomcat7-3.2.X.tar.gz or cams-webagent-tomcat7-3.2.X.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 7.x installation home directory.

NOTE: The Cams Tomcat 7 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-tomcat7-3.2.X/...

Step 1: Extract the Cams Tomcat 7 web agent Files

Linux/UNIX

cd /tmp
tar xvfz cams-webagent-tomcat7-3.2.X.tar

Windows

cd C:\temp
pkunzip cams-webagent-tomcat7-3.2.X.zip

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

<!-- Cams Tomcat 7 web agent documentation and license -->
README.txt
LICENSE
ReleaseNotes.html

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

<!-- Cams Tomcat 7 web agent Java libraries -->
lib/cams.jar
lib/cams-common.jar
lib/cams-webagent-tomcat7.jar
lib/cscore.jar
lib/infinitemonkey.dll
lib/InfiniteMonkey.jar
lib/log4j.jar

<!-- Cams Tomcat 7 web agent login, test, and error pages -->
cams/camstest.jsp
cams/login.jsp
cams/slo.jsp
cams/slo.gif
cams/error/403.html
cams/error/500.html
cams/error/default_error.html
cams/WEB-INF/web.xml

Figure 1 - Directory listing of the Cams Tomcat 7 web agent files after extraction

Step 2: Copy Cams Tomcat 7 Web Agent Files to CATALINA_HOME

Linux/UNIX

cd cams-webagent-tomcat7-3.2.X
cp -r cams $CATALINA_HOME/webapps
cp conf/* $CATALINA_HOME/conf
cp lib/* $CATALINA_HOME/lib

Windows

cd cams-webagent-tomcat7-3.2.X
xcopy cams %CATALINA_HOME%\webapps\cams /S /I
xcopy conf %CATALINA_HOME%\conf
xcopy lib %CATALINA_HOME%\lib

Web Agent Configuration

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

NOTE: To secure resources on your Tomcat 7 server, you'll also need to configure a Cams security domain. See the Cams Policy 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. You can also reference more detailed information on the properties in the Configuration Properties document.

NOTE: The most important properties are at the top of cams-webagent.conf. In most cases, the default property values will work if the Cams policy server and Cams web agent are on the same host. As you begin to integrate more web and application servers, reference Configuration Properties to understand the properties that will usually be the focus of your attention.

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 7 web 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.tomcat7.ErrorReportValve"
  errorPageDir="${catalina.home}/webapps/cams/error/"
  defaultErrorPageFilename="default_error.html"
  debug="false" />
<Valve className="com.cafesoft.security.webagent.tomcat7.CamsTomcat7WebAgent"
  configPath="${catalina.home}/conf/cams-webagent.conf"
  contextClass="com.cafesoft.security.common.agent.StandardCamsAgentContext"/>

NOTE: The Cams-provided ErrorReportValve is used before the CamsTomcat7WebAgent valve so that an HTML-formatted error page is returned to the HTTP client should Cams deny access to the requested resource (by returning HTTP status 403 - Forbidden) or should a serious internal server error be reported (by returning HTTP status 500 - Internal Server Error). The Cams-provided ErrorReportValve looks in the directory specified by the errorPageDir property for a file named <HTTP response status>.html and returns the contents of that file if found. If a specific error page file is not found, then a default error page file is returned (if that is found). If no error page files are found, then a hard-coded error page that mimics the look of standard Tomcat error pages is returned. The ErrorReportValve will not return an error page if content has already been returned to the HTTP client by a Host-level valve or a web application.

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 web agent.

<Realm className="com.cafesoft.security.webagent.tomcat7.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 UserDatabaseRealm enabled. Comment-out the UserDatabaseRealm by placing the XML closing comment tag after the Realm tag:

The Cams Tomcat 7 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 UserDatabaseRealm in both services and add the Cams Tomcat 7 web agent valve and realm to each.

NOTE: The default Tomcat UserDatabaseRealm uses the UserDatabase <GlobalNamingResources>, which is no longer used if the UserDatabaseRealm is disabled. You can safely disable the UserDatabase <GlobalNamingResources> by commenting it out.

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Tomcat 7 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 Tomcat security tags from each webapp's web.xml descriptor file.

Java Server Pages

The distribution cams directory is a J2EE compliant webapp that includes two sample Java Server Pages (JSP) for user interaction:

camstest.jsp - facilitates integration testing
login.jsp - displays a login page if a protected resource request is made and the user's identity is not known

For information on how to customize the login page, see Scripts.

NOTE: The camstest.jsp page is extremely useful for integration testing. You use it to quickly confirm correct Cams web agent communications with a Cams policy server, validate authentication configuration, and determine if expected user session values are available in the web environment for authenticated users.

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/Vista/7/2008/8/2012). The general strategy for securing Cams-related configuration files and directories is to:

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 7 web agent to run within the secured file and directory environment described below.
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.
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:

Tomcat is installed at /usr/local/jakarta-tomcat, hereafter referred to as CATALINA_HOME
The Tomcat configuration directory is at CATALINA_HOME/conf
The Tomcat logs directory is at CATALINA_HOME/logs
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 7 web agent configuration and/or log files.

Step 1 - Change directories to the Tomcat installation directory

cd /user/local/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:

Tomcat is installed at C:\tomcat, hereafter referred to as CATALINA_HOME
The Tomcat configuration directory is at CATALINA_HOME\conf
The Tomcat logs directory is at CATALINA_HOME\logs
You are logged in as Admininistrator to your Windows XP/2003/Vista/7/2008/8/2008 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 XP/2003/Vista/7/2008/8/2008 graphical user interface.

Using the Windows Explorer file browser, select the top-level Tomcat installation directory: C:\jakarta-tomcat
Right click on the folder and select Properties from the pop-up menu
In the dialog box that appears, select the Security tab
Click on the Ownership button
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:\tomcat used in Step 1:

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

Cams Policy Server Configuration

Before you start the Tomcat server with a Cams Tomcat 7 web agent, you'll need to ensure that the Cams policy server knows about it. See the Cams Administrator's Guide - Integration Quick Start to learn more. Pay close attention during integration to steps 4 and 5, which provide information on the settings that must be configured correctly for a Cams web agent to connect to a Cams policy server. You'll need to configure an access control policy corresponding to your site requirements.

Testing

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

http://[hostname:port]/cams/camstest.jsp

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

Debugging

Debugging information is available in the following web server-specific log files:

The Tomcat 7 server console log (CATALINA_HOME/logs/catalina.out)
The Cams web agent cams-webagent.log file (CATALINA_HOME/logs/cams-webagent.log)

During Cams web agent integration, it is helpful to set the following values in cams-webagent.conf:

cams.debug=true
cams.cluster.debug=true

If the Cams web agent is successfully loaded and initialized, verbose DEBUG messages will be logged to cams-webagent.log. If the Cams web agent fails to load or initialize, errors will be reported in the CATALINA_HOME/logs/catalina_out file. In most cases, errors will be cause by misconfigured values in server.xml and/or cams-webagent.conf.

WARNING: Remember to disable all Cams web agent debug flags for production environments. Leaving them enabled will decrease performance and result in very large log files.

Back | Next | Contents