Back | Next | Contents Cams Web Agent Guide

Servlet Filter Web Agent Integration

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

This document provides instructions on how to install and configure the Cams Servlet Filter web agent, which is a Java J2EE Servlet Filter implementation that provides web resource security on Java J2EE servers supporting Servlet API version 2.3 or greater.

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

Installation

These instructions guide you through the installation of the Cams Servlet Filter web agent using the reference Java J2EE Servlet and JavaServer Pages technology implementation, Apache Tomcat. Installation instructions are also provided for Red Hat JBoss. If you are using another Java J2EE server, such as Oracle WebLogic or IBM WebSphere, please also reference the vendor's documentation for installation of a Servlet Filter as needed.

Each Java J2EE server has different directory structures where you copy the Cams Servlet Filter web agent libraries and configuration files. You must decide whether to install the Cams Servlet Filter web agent libraries and configuration file in a global context location, or within each web application context. We recommend you use a global context unless you have good reason to choose a web application context. You must also decide if you want all Cams Servlet Filter instances deployed in your Java J2EE server to share the same web agent instance and connections to the Cams policy server or use separate web agent instances and connections.

NOTE: Instructions on how to configure the Cams Servlet Filter web agent for shared global server or instance-specific integrations are found in Editing web.xml.

Shared Global Configuration Advantages

  • Centralizes and simplifies configuration and management, including for Cams Servlet Filter web agent upgrades
  • Increases throughput and lowers memory requirements using efficient, shared connections to the Cams policy server
  • Shares logging and resource caching

Instance-specific Web Application Configuration Advantages

  • Configuration and management is decentralized and custom for each web application
  • Libraries and configuration files can be checked into a source control system as a cohesive component of each web application
  • Each web application has it's own Cams Servlet Filter web agent instance and connections to the Cams policy server(s)
  • Web application-specific Cams logs and resource caching

Download the Cams Servlet Filter web agent. If you are not a currently registered customer or evaluator, you will also need to request an evaluation license.

Unpack the download (cams-webagent-servletFilter-3.2.X.tar.gz or cams-webagent-servletFilter-3.2.X.zip) into an installation directory of your choosing (referred to as INSTALL_DIR in the remainder of this document).

Linux/UNIX

tar xvfz cams-webagent-servletFilter-3.2.X.tar.gz

Windows

pkunzip cams-webagent-servletFilter-3.2.X.zip

Change to the created directory. The files in Figure 1 should have been extracted into the directory.

<!-- Release notes and licenses -->
LICENSE
README.txt ReleaseNotes.html
THIRD_PARTY_LICENSES

<!-- Scripts for creating cams.war --> bin/create_cams_war.bat bin/create_cams_war.sh <!-- The "cams" web application supplies the login and test pages --> cams/camstest.jsp cams/login.jsp
cams/slo.gif
cams/slo.jsp
cams/WEB-INF/web.xml <!-- Cams Servlet Filter web agent configuration file --> conf/cams-webagent.conf <!-- Cams Servlet Filter web agent Java libraries --> lib/cams.jar lib/cams-common.jar lib/cams-webagent-servletFilter.jar lib/cscore.jar lib/InfiniteMonkey.jar lib/infinitemonkey.dll
lib/log4j.jar

<!-- Open source required by author license to be included -->
public/Base64.c
public/Base64.java
public/HexUtils.c
public/UnixCrypt.java

Figure 1 - Directory listing of the Cams Servlet Filter web agent files after unpacking

Installation is a five step process for any Java J2EE server:
  1. Shutdown the Java J2EE server (this may not be required if the installation is within web application context).
  2. Copy the Cams Servlet Filter web agent's lib files into a global server directory (recommended) or into each web application's lib directory (the Java J2EE standard is the WEB-INF/lib directory) for each Cams protected web application.
  3. Configure connection to your Cams policy server(s) by editing cams-webagent.conf and then copy the file for global or web application-specific reference. NOTE: You may use more than one cams-webagent.conf if you have settings that are web application specific.
  4. Edit web.xml in the cams web application with the path to the cams-webagent.conf configuration file and install in the Java J2EE server's web application deployment directory. You can install the expanded cams web application or use the create_cams_war.bat/sh scripts in the bin directory to build a cams.war web application archive (war) file. Edit web.xml before you create cams.war so the web application deploys in a ready state. The cams web application provides an example login.jsp page which you should customize. Alternatively, you can integrate the login.jsp page into another web application also configured with the Cams Servlet Filter web agent. You will also need to similarly edit web.xml for all your Java J2EE server web applications that will use Cams security.
  5. Start (if required) your J2EE server and Test

The next sections step you through installation with:

If you are using another Java J2EE server, reference your server's documentation for the information on where to install global libraries and other Cams Servlet Filter web agent resources. If you have difficulties, please contact Caf�soft support with the J2EE server name and version number.

Tomcat Installation

These installation instructions may be used with either Tomcat 6 or 7. Before installing the Cams Servlet Filter web agent, make sure that Tomcat is installed and working correctly. This document uses CATALINA_HOME to refer to the location where Tomcat is installed.

Step 1 - Shutdown Tomcat

Shutdown Tomcat if you are installing the Cams Servlet Filter web agent libraries into the global CATALINA_HOME/lib directory. Upon restarting, these libraries then become available to all Tomcat server instance web applications. If you install the libraries into each web application's /WEB-INF/lib directory, you can alternatively restart only the web application. Depending upon how your Tomcat is configured, changes to web.xml will automatically trigger a web application restart. You may also deploy and restart web applications using the Tomcat Manager. 

Step 2 - Copy the Libraries

We recommend you copy all files from INSTALL_DIR/lib into the CATALINA_HOME/lib directory for use by all JBoss server instance web applications. You may alternatively copy all files from INSTALL_DIR/lib into EACH target web application's /WEB-INF/lib directory.

Step 3 - Configure and Copy cams-webagent.conf

Configure the Cams Servlet Filter web agent's INSTALL_DIR/conf/cams-webagent.conf for connection to your Cams policy server(s) as described in Web Agent Configuration.

For Tomcat global context installation, copy the configured INSTALL_DIR/conf/cams-webagent.conf into the CATALINA_HOME/conf directory.

For web application context installation, copy the configured INSTALL_DIR/conf/cams-webagent.conf into each target web application's /WEB-INF directory.

NOTE: The cams-webagent.conf directory locations are suggestions. You may copy cams-webagent.conf into the directory of your choice by specifying the location in the Cams Servlet Filter web agent's configuration elements in web.xml.

Step 4 - Configure and Install the cams Web Application

Edit INSTALL_DIR/cams/WEB-INF/web.xml as described in Editing web.xml. Ensure that you correctly reference the location of cams-webagent.conf. Create the cams.war web application using the INSTALL_DIR/bin/create_cams_war.bat/sh tool and deploy by copying into CATALINA_HOME/webapps or by using the Tomcat Manager. 

NOTE: You must add the Cams Servlet Filter web agent to each web application that will be protected by Cams by making the edits as described in Editing cams-webagent.conf. Also, ensure that the Cams Servlet Filter libraries are either globally available or copied into /WEB-INF/lib.

Step 5 - Test

Start Tomcat or the web application. View CATALINA_HOME/logs/cams-webagent.log to verify that the Cams Servlet Filter web agent has initialized connections to the Cams policy server and that there are no errors. Use  http://localhost:8080/cams/camstest.jsp to test login, or try to access a protected resource for redirection to your configured login page.

JBoss Standalone Installation

These installation instructions may be used with either JBoss 6 or 7. Before installing the Cams Servlet Filter web agent, make sure that JBoss is installed and working correctly in a standalone configuration. This document uses JBOSS_HOME to refer to the location where Tomcat is installed.

NOTE: Installation of the Cams Servlet Filter web agent in a JBoss domain configuration is not documented.

Step 1 - Shutdown JBoss

Shutdown JBoss if you are installing the Cams Servlet Filter web agent libraries into the global JBOSS_HOME/modules directory. Upon restarting, these libraries then become available to all JBoss server instance web applications. If you install the libraries into each web application's /WEB-INF/lib directory, you can alternatively restart only the web application. Depending upon how your JBoss is configured, changes to web.xml will automatically trigger a web application restart. You may also deploy and restart web applications using the JBoss Management web application. 

Step 2 - Copy the Libraries

We recommend you copy all files from INSTALL_DIR/lib into a Cams Servlet Filter web agent global module for use by all JBoss server instance web applications. To do so, create the JBOSS_HOME/modules/com/cafesoft/sfwa/main directory. Copy all files from INSTALL_DIR/lib into JBOSS_HOME/modules/com/cafesoft/sfwa/main. Create module.xml in JBOSS_HOME/modules/com/cafesoft/sfwa/main with the elements shown in Example 1.

<?xml version="1.0" encoding="UTF-8"?>

<module xmlns="urn:jboss:module:1.1" name="com.cafesoft.sfwa">
    <resources>
        <resource-root path="cams.jar"/>
        <resource-root path="cams-common.jar"/>
        <resource-root path="cams-webagent-servletFilter.jar"/>
        <resource-root path="cscore.jar"/>
        <resource-root path="InfiniteMonkey.jar"/>
        <resource-root path="log4j.jar"/>
    </resources>

    <dependencies>
	<module name="javax.api"/>
	<module name="javax.servlet.api"/>
    </dependencies>
</module>

Example 1 - Configuring module.xml for the Cams Servlet Filter web agent module

Open the JBoss standalone configuration file JBOSS_HOME/standalone/configuration/standalone.xml in a text or XML editor. Add the Cams Servlet Filter web agent module into the urn:jboss:domain:ee:1.0 namespace as shown in bold red in Example 2.

NOTE: You may also use the JBoss Management application to add the Cams Servlet Filter web agent global module by clicking Add under Profile -> Container -> EE. Use the module name com.cafesoft.sfwa and slot main.

<subsystem xmlns="urn:jboss:domain:ee:1.0">
  <global-modules>
    <module name="com.cafesoft.sfwa" slot="main"/>
  </global-modules>
</subsystem>

Example 2 - Configuring JBoss standalone with the Cams Servlet Filter web agent module

You may alternatively copy all files from INSTALL_DIR/lib into EACH target web application's /WEB-INF/lib directory.

Step 3 - Configure and Copy cams-webagent.conf

Configure the Cams Servlet Filter web agent's INSTALL_DIR/conf/cams-webagent.conf for connection to your Cams policy server(s) as described in Web Agent Configuration.

For JBoss global context installation, copy the configured INSTALL_DIR/conf/cams-webagent.conf into the JBOSS_HOME/standalone/configuration directory.

For web application context installation, copy the configured INSTALL_DIR/conf/cams-webagent.conf into each target web application's /WEB-INF directory.

NOTE: The cams-webagent.conf directory locations are suggestions. You may copy cams-webagent.conf into the directory of your choice by specifying the location in web.xml.

Step 4 - Configure and Install the cams Web Application

Edit INSTALL_DIR/cams/WEB-INF/web.xml as described in Editing web.xml. Ensure that you correctly reference the location of cams-webagent.conf. Create the cams.war web application using the INSTALL_DIR/bin/create_cams_war.bat/sh tool. Copy cams.war into JBOSS_HOME/deployments. You may also use the JBoss Management application to add cams.war by clicking Add Content under Runtime -> Deployments -> Manage Deployments (make sure you Enable the content). 

NOTE: You must add the Cams Servlet Filter web agent to each web application that will be protected by Cams by making the edits as described in Editing cams-webagent.conf. Also, ensure that the Cams Servlet Filter libraries are either globally available or copied into /WEB-INF/lib.

Step 5 - Test

Start the JBoss server or the web application. View JBOSS_HOME/logs/cams-webagent.log to verify that the Cams Servlet Filter web agent has initialized connections to the Cams policy server and that there are no errors. Use http://localhost:8080/cams/camstest.jsp to test login, or try to access a protected resource for redirection to your configured login page.

Web Agent Configuration

The Cams Servlet Filter web agent is configured in cams-webagent.conf. Most Java J2EE server configurations share only one cams-webagent.conf file between all web applications. To share the same cams-webagent.conf between web applications, simply specify the same cams-webagent.conf file path in the configPath parameter for each web application's web.xml file (see Editing web.xml).

It is possible to use different cams-webagent.conf files for each web application secured by a Cams Servlet Filter web agent. For example, you may desire for each web application to have a custom log file. To do so, specify the unique name or path for each cams-webagent.conf file you configure in web.xml for EACH web application. Then follow the configuration instructions below for each file.

NOTE: To secure resources on your Java J2EE 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 web.xml

You must add a reference to the Cams Servlet Filter web agent in web.xml for EACH web application that requires Cams security. Add the filter and filter mapping as shown in Example 3. Make sure that your replace the fully_qualified_path, shown in bold red in Example 3, with a fully-qualified file path of your choosing to the appropriate cams-webagent.conf file. This is the only value you need to change unless you need to further qualify the URLs to which Cams security will be applied by change the <url-pattern> value.

WARNING: The Cams Servlet Filter web agent should be first in the filter chain so that it can determine if access should be granted. Also, if any of the web.xml optional icon, display-name, description, distributable or context-param elements are in use, the Cams Servlet filter element should be placed below them and before any listener, servlet, servlet-mapping, session-config, mime-mapping, welcome-file-list, error-page, taglib, resource-env-ref, resource-ref, security-constraint, login-config, security-role, env-entry, ejb-ref, ejb-local-ref elements. Generally, any security-constraint, login-config, security-role security elements should be commented out, with Cams used for web application security instead of the Java J2EE server container provided security.

<Web-app>

 ...

 <filter>
  <filter-name>Cams Servlet Filter Web Agent</filter-name>
  <filter-class>com.cafesoft.security.webagent.servletFilter.CamsServletFilterWebAgent</filter-class>

  <init-param>
   <param-name>configPath</param-name>
   <param-value>/fully_qualified_path/cams-webagent.conf</param-value>
  </init-param>

  <init-param>
   <param-name>contextClass</param-name>
   <param-value>com.cafesoft.security.common.agent.StandardCamsAgentContext</param-value>
  </init-param>
 </filter>

 <filter-mapping>
  <filter-name>Cams Servlet Filter Web Agent</filter-name>
  <url-pattern>/*</url-pattern>
 </filter-mapping>

 ...

</web-app>

Example 3 - Configuring a web application to use the Cams Servlet Filter web agent

Filter Values

  • filter-name (required) - The filter name
  • configPath (required) - The fully-qualified file path to cams-webagent.conf. Use forward slashes or optionally backward slashes on Windows.
  • contextClass (required) - The fully-qualified class name of the Cams agent context implementation
Filter Mapping Values
  • filter-name (required) - The filter name
  • URL-pattern (required) - The URLs within this web application that the Cams Servlet Filter web agent will protect. Use "/*" to protect the entire web application.

Java Server Pages

The distribution cams directory is a J2EE web application that includes example Java Server Pages (JSP) for user interaction:

  • camstest.jsp - Used for integration testing
  • login.jsp - Displays a Cams login page if a protected resource request is made and the user's identity is not known and the camsLoginUrl in the security domain's login-config.xml for the associated <login-config-entry> instructs the Cams web agent to redirect to a URL that references this page.
  • slo.jsp - Logs a user out of two or more DNS domains when Cams Cross DNS Single Sign-on (CDSSO) is configured.

For information on how to customize these pages, see Scripts. For information on how to configure the Cams web agent to redirect to these pages, see Configuration Properties.

NOTE: The camstest.jsp page is 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.

Cams Policy Server Configuration

Before you start your Java J2EE server with a Cams Servlet Filter web agent, you must ensure that the Cams policy server is correctly configured and available. 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

You should now be able to start your Java J2EE server to test your Cams Servlet Filter web agent configuration. After you've started both the Java J2EE server with the Cams Servlet Filter web agent and the Cams policy server, test your 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.

NOTE: If the Cams Servlet Filter web agent fails to load correctly, it will unconditionally deny access to the web application resources.

Debugging

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

  1. The Java J2EE server-specific error log file (see your Java J2EE server documentation)
  2. 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 are logged to cams-webagent.log. If the Cams web agent fails to load or initialize, errors are reported in the Java J2EE server error file. In most cases, errors are caused by misconfigured values in the Java J2EE server-specific configuration values and/or cams-webagent.conf.

WARNING: Remember to disable Cams web agent debug flags for production environments. Leaving them enabled will decrease performance and result in large log files that may fill your system's hard disk.

Back | Next | Contents