Back | Next | Contents | Cams Web Agent Guide |
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.
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/...
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
Linux/UNIX
cd cams-webagent-tomcat7-3.2.X
cp -r cams $CATALINA_HOME/webapps
cp conf/* $CATALINA_HOME/conf
cp lib/* $CATALINA_HOME/libWindows
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
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.
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.
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:
<!--
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
debug="0" resourceName="UserDatabase"/>
-->
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.
The distribution cams directory is a J2EE compliant webapp that includes two sample Java Server Pages (JSP) for user interaction:
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.
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:
The following sections provide operating system-specific instructions for securing Cams web agent files and directories in the Tomcat environment.
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:
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.
cd /user/local/tomcat
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.
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.
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:
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:
This is done using the Windows XP/2003/Vista/7/2008/8/2008 graphical user interface.
From the same Security tab in the context-sensitive dialog box for directory C:\tomcat used in Step 1:
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.
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 information is available in the following web server-specific log files:
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.