| 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 is 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 Servlet Filter web agent. The Cams Servlet Filter web agent is a Java J2EE servlet filter implementation that provides web content security on J2EE servers that supports the Servlet 2.3 API.
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.
These instructions guide you through the installation of Cams Servlet Filter web agent on a system with a J2EE server already installed. If a J2EE server is not yet installed, you must first do so. You must also 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-2.0.X.tar.gz or cams-webagent-servletFilter-2.0.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-2.0.X.tar.gz
Windows
pkunzip cams-webagent-servletFilter-2.0.X.zip
Change directories to the directory that was created. The files shown in Figure 1 should have been extracted from the distribution into the directory.
<!-- Cams Servlet Filter web agent documentation and license --> README.txt LICENSE.txt ReleaseNotes.html <!-- Scripts for creating cams.war --> bin/create_cams_war.bat bin/create_cams_war.sh <!-- The "cams" web application supplies the login, denied, and error pages --> cams/cams-webagent-test.jsp cams/denied.jsp cams/error.jsp cams/login.jsp cams/secured-by-cams.gif cams/WEB-INF 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-webagent-servletFilter.jar lib/cams-common.jar lib/cams.jar lib/cscore.jar lib/log4j.jar lib/InfiniteMonkey.jar lib/infinitemonkey.dll lib/InfiniteMonkeyLicense.txt |
| Figure 1 - Directory listing of the Cams Servlet Filter web agent files after unpacking |
Each J2EE server has different directory structures where you will need to copy the Cams Servlet Filter web agent libraries and configuration files. From a high-level, installation is a six step process:
The next sections step you through installation for specific J2EE servers on which the Cams Servlet Filter web agent has been tested. If server-specific instructions are not available for the J2EE server you are using, try following the server neutral steps specified above. If you have difficulties, please contact Cafésoft support with the J2EE server name and version number. The tested J2EE servers include:
NOTE: All tests with J2EE servers that implement Servlet specification 2.3 have been successful. Other J2EE servers that support Servlet specification 2.3 are likely to work and will be added as they are tested.
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).
Before installing the Cams Servlet Filter web agent, make sure that WebLogic is installed and working on your system. The documentation will use YOUR_DOMAIN to represent the location where your WebLogic server domain is installed. If you are unfamiliar with the server domain concept please read the documentation provided by BEA.
To install the Cams Servlet Filter web agent on BEA Weblogic 8.1 perform the following steps:
Before installing the Cams Servlet Filter web agent, make sure that Oracle 9iAS 9.0.x is installed and working on your system. This document will use ORACLE_HOME to represent the location where Oracle 9iAS OC4J is installed. If you have difficulties installing the Cams Servlet Filter web agent with Oracle 9iAS, check the log files in ORACLE_HOME/opmn/logs for errors or warnings.
To install the Cams Servlet Filter web agent on Oracle 9iAS 9.0.x, perform the following steps:
NOTE: Resources that are mapped to Oracle's Apache web server are not protected by the Cams Servlet Filter web agent. If you need to protect these ressources as well as the servlet/JSP resources, you can use the Cams Apache web agent on supported operating systems.
Before installing the Cams Servlet Filter web agent, make sure that JBoss is installed and working on your system. This document will use JBOSS_HOME to represent the location where JBoss is installed.
To install the Cams Servlet Filter web agent on JBoss 3.2.x perform the following steps:
Before installing the Cams Servlet Filter web agent, make sure that Jetty is installed and working on your system. This document will use JETTY_HOME to represent the location where Jetty is installed.
To install the Cams Servlet Filter web agent on Jetty 4.2.x perform the following steps:
Before installing the Cams Servlet Filter web agent, make sure that Tomcat is installed and working on your system. This document will use CATALINA_HOME to represent the location where Tomcat is installed.
To install the Cams Servlet Filter web agent on Tomcat perform the following steps:
Before installing the Cams Servlet Filter web agent, make sure that WebSphere Application Server (WAS) is installed and working on your system. This document will use WAS_HOME to represent the location where WAS is installed.
Here is an overview of the steps needed to install the Cams ServletFilter web agent under WAS 5.1:
This step will enable multiple web applications deployed on WAS to use the same Cams ServletFilter Web Agent configuration file and libraries. The goal is to create the following directory/file hierarchy by copying a subset of files from INSTALL_DIR:
WAS_HOME/cams/conf/cams-webagent.conf WAS_HOME/cams/lib/cams.jar WAS_HOME/cams/lib/cams-common.jar WAS_HOME/cams/lib/cams-webagent-servletFilter.jar WAS_HOME/cams/lib/cscore.jar WAS_HOME/cams/lib/infinitemonkey.dll WAS_HOME/cams/lib/InfiniteMonkey.jar WAS_HOME/cams/lib/InfiniteMonkeyLicense.txt WAS_HOME/cams/lib/log4j.jar
(NOTE: The Cams libraries and configuration file will be made accessible to one or more web applications).
To create the specified directory/file hierarchy:
The "cams" web application contains various Java Server Pages, including: login.jsp, error.jsp, login.jsp, and cams-webagent-test.jsp, which are referenced by the Cams ServletFilter Web Agent configuration and the Cams Policy Server. It also registers the Cams ServletFilter Web Agent for protection, so correctly configuring this application will serve as a model for integrating the Cams ServletFilter Web Agent with other web applications.
The "cams" web application contains various Java Server Pages, including: login.jsp, error.jsp, login.jsp, and cams-webagent-test.jsp, which are referenced by the Cams ServletFilter Web Agent configuration and the Cams Policy Server. It also uses the Cams ServletFilter Web Agent for protection, so correctly configuring this application will serve as a model for integrating the web agent with other applications (if needed).
This step will create a web application archive file named "cams.war" that includes the newly edited web.xml file and the .jsp files used as login, error, and access denied pages by Cams. It will be deployed on WAS using the WAS admin console.
Before you can complete this step, you'll need to:
Once you have access to the WAS admin console:
This step will enable convient "binding" of the "cams" web application a WAS shared library, which contains the .jar files needed for the web agent to execute. Creation of the WAS shared library will conveniently enable you to bind future web applications that need protection by the Cams ServletFilter Web Agent.
In the WAS admin console:
C:/Program Files/WebSphere/AppServer/cams/lib/cscore.jar C:/Program Files/WebSphere/AppServer/cams/lib/cams.jar C:/Program Files/WebSphere/AppServer/cams/lib/cams-common.jar C:/Program Files/WebSphere/AppServer/cams/lib/log4j.jar C:/Program Files/WebSphere/AppServer/cams/lib/InfiniteMonkey.jar C:/Program Files/WebSphere/AppServer/cams/lib/cams-webagent-servletFilter.jar
This step "binds" the "cams" web application with the "cams-webagent" shared library, enabling it to access the associated .jar files and native binaries.
The "cams" web application should now be started and available. To confirm proper operation, try accessing the Cams webagent test page.
For example: http://localhost:9080/cams/cams-webagent-test.jsp
If the test page fails to load, you'll need to debug the installation by looking at the Cams web agent and WAS log files and taking appropriate corrective actions. Based on the installation instructions above, you can find these log files at:
WAS_HOME/logs/cams-webagent.log WAS_HOME/AppServer/logs/<server name>
NOTE: You'll need to look in the approprate directory for the WAS server name configured on your system.
The Cams Servlet Filter web agent is configured in cams-webagent.conf. You also need to edit the web.xml configuration file for all web applications that will use the Cams Servlet Filter Agent and integrate the Cams login.jsp, error.jsp, and denied.jsp pages.
Most J2EE server configurations should share only one cams-webagent.conf file between all webapps. Using a shared configuration file has the following benefits:
To share cams-webagent.conf between web applications, simply specify the same cams-webagent.conf file in the configPath parameter for each web application's web.xml file.
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 login.jsp, error.jsp, and denied.jsp page. To do so, specify a unique name or path for each cams-webagent.conf file in web.xml for each web application. Then follow the configuration instructions below for each file.
NOTE: To secure resources on your 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.
Open 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.
| Name | Description |
|---|---|
| cams.cluster.name |
The name of the Cams cluster to which this Cams web agent will delegate requests. This value is used to identify Cams session cookies originating from a Cams cluster installation. The default value is MyCamsCluster. NOTE: Every Cams policy server is a member of a cluster, even if the cluster contains only a single Cams policy server. |
|
cams.server.url.<server-name> |
The URL of a Cams policy server to be used. The actual name of the configuration property will depend on the Cams policy server name. For example:
One property must exist for each Cams policy server in your cluster. For example, the following properties configure an agent for a two node Cams policy server cluster:
Each URL has the form: cams://host:port, where host is a host name or an IP address. For example:
WARNING: If the Cams Servlet Filter web agent and Cams policy server communicate through a firewall, the firewall must be configured to allow general TCP/IP traffic on the configured Cams policy server port. |
| cams.heartbeat.interval | The interval (in seconds) the Cams Web Agent will send heartbeat messages to the Cams Policy Server to ensure it's availability. |
| cams.cluster.debug |
Toggle on/off clustering debug messages. WARNING: Turning on debug can have an adverse affect on Cams web agent performance. |
| cams.debug |
Toggle on/off debug messages. WARNING: Turning on debug can have an adverse affect on Cams web agent performance. |
| cams.error.url |
The relative or fully qualified URL to redirect to if an error occurs during authentication or when accessing a protected resource. WARNING: The access control policy must ensure that access to the error page is granted. |
| cams.denied.url |
The relative or fully qualified URL to redirect to if access to a protected resource is denied by the Cams policy server. WARNING: The access control policy must ensure that access to the denied page is granted. |
| cams.login.uri |
The Cams Servlet Filter web agent will interpret POST requests to this exact URI as a login (authentication) request. The login URI can be on a different system from the one making the request. Posted parameters (usually hidden fields) MUST include:
and will also usually include callback parameters used by Cams policy server login modules. For example:
The actual callback parameters posted must match those expected by the callback handler login module configured with the specified security domain/login config entry. |
| cams.logout.uri |
The Cams Servlet Filter web agent will interpret any request to this exact URI as a logout request. The logout URI can be on a different system from the one making the request. Because a given user may be logged into multiple security domains simultaneously, the web page referencing this URI must specify the security domain name associated with the logout request as a query parameter. For example, if a webagent hosted on web server www.mysite.com has: cams.logout.uri=/cams/logout then the following request will attempt to logout the user that is logged into security domain system: http://www.mysite.com/cams/logout?cams_security_domain=system |
| cams.after.logout.url | The URL to which a user is directed AFTER successful logout. This might be a web site or portal home page. |
| cams.loginconfig.entry | The login-config-entry to use to authenticate clients. This value corresponds to a login-config-entry that is defined in the corresponding security domain's login-config.xml file, which defines the login modules, callback handler, and any login parameters. Typically, the type value http is used for web resources. |
| cams.access.check.cache |
Enable/disable the access control check cache. Caching improves performance by enabling the web agent to remember a previous access control check Cams policy server response for a specified period of time. The Cams Servlet Filter web agent currently caches ONLY responses associated with unconditionally granted resources. This enables general resources like GIF and JPEG image files, javascript, style sheets, to avoid unnecessary access control checks. Access to a resource protected by a Cams access control policy is unconditionally granted if the permission matching the resource directly referencse a Cams intrinsic access control rule. |
| cams.access.check.cache.size | The maximum number of access control responses that can be cached at a given time. Once the cache is full, newly cached responses will eject the least recently used cached response. |
| cams.access.check.cache.refreshTime | The amount of time, in minutes, that is allowed before an access control request is sent to the Cams policy server to check if the cache should be cleared. This ensures that Cams web agent can detect changes to a Cams access control policy within this period, forcing the cache to be flushed if necessary. |
| cams.session.cache | Enable/disable session caching. Session caching enables the servlet API and cgi-bin applications to access Cams policy server session attributes as HTTP Request header values. |
| cams.session.hijacking.protection.enable |
Enable/disable Cams session hijacking protection. Use true
to enable and false to disable
hijacking protection. An extra hash value is appended to the base session
identifer and validated each time a Cams session id cookie value is received.
Unless the request is received from an HTTP browser with the same HTTP
request headers (Accept-Language and User-Agent) the session is considered |
| cams.session.hijacking.protection.algorithm |
The message digest algorithm used to compute a unique hash value for hijacking protection. The following algorithms are supported:
|
| cams.session.hijacking.protection.salt |
A unique site value combined as an ingredient with all other session and HTTP request header parameters to ensure that the message digest hash value is unique for a given deployment environment. The default value is epsom. NOTE: Choose a value unique to your site for maximum protection. |
| cams.http.headers | Enable/disable setting of Cams HTTP request headers. If enabled web pages, servlets, JSPs, and cgi-bin scripts will have access to HTTP request headers. See the Cams Programmer's Guide - Webapp Programming for a full list of the HTTP request header names and site-specific user attribute values that can be made available to web applications. Disabling Cams request headers when not used improves performance. |
| cams.http.headers.accept.proxied | Enable the agent to accept CAMS HTTP Headers that have been proxied to this web agent via another Cams web agent. The default value is false. |
| connection.authentication.type |
The type of authentication the Cams Servlet Filter web agent will use to authenticate connections that it establishes with the Cams policy server. Currently supported types include:
NOTE: This is NOT the authentication type used to authenticate users, it is the type used to authenticate the Cams web agent. |
| connection.authentication.principal | The principal (or username) the Cams Servlet Filter web agent will use to authenticate connections it establishes with the Cams policy server. |
| connection.authentication.credential | The credential (or password) the Cams Servlet Filter web agent will use to authenticate connections it establishes with the Cams policy server. |
| connection.authentication.timeout | The maximum time (in seconds) that the Cams Servlet Filter web agent will wait for a response from the Cams policy server. If a response has not been returned by the Cams policy server within the allotted timeout period then authentication fails. |
| connection.pool.lazyConnect | The lazyConnect value is a boolean flag. If the value of the property is true the Cams web agent will not attempt to connect to the Cams policy server until a request has been made. If the value of the property is false the Cams web agent will connect to the Cams policy server immediately. |
| connection.pool.maximum | The maximum is the maximum number of Connections the Cams web agent is allowed to have with a Cams policy server. |
| connection.pool.socket.maximum | The maximum number sockets allowed on a particular Connection. This value can be increased to allow for more data to be sent across a single connection. However, it is not recommended that this value exceed 20. |
| cams.skey.algorithm |
The algorithm to be used when encrypting and decrypting selected values sent to/received from the Cams server. Valid values include: None, Blowfish, DES, and DESede (triple DES). If None, then selective encryption is disabled. Blowfish uses a 16 byte encryption key, DES uses an 8 byte key, and DESede uses a 24 byte key. For more information, see: Cams Administrator's Guide - Securing Cams Communications using Secret Keys. |
| cams.skey.key | The secret encryption/decryption key in hexidecimal format. The actual number of bytes used depends on the algorithm, although it is legal to supply more key bytes than needed. |
|
cams.skey.iv |
The encryption/decryption initialization vector in hexidecimal format. This should be an 8 byte (16 hex digit) value. |
| logger.class | (REQUIRED) The fully qualified Java classname of the Logger. |
| logger.file.path |
(REQUIRED) The fully qualified log file path. NOTE: You should use a fully qualified path. If the directory(s) specified is missing, it will be created. |
| logger.file.append | (OPTIONAL) If true new log messages will be appended to the current log file. If false the current log file will be deleted and a new log file will be created. The default value is true. |
| logger.file.bufferedIO | (OPTIONAL) If true the logger will buffer log messages before writing them to the log file. This can significantly improve logging performance. The default is true. |
| logger.file.bufferSize | (OPTIONAL) Indicates the size of the buffer to fill before writing to the log file. The default is 4096. |
| logger.file.maxSize |
(OPTIONAL) The maximum size the logfile is allowed to grow before creating a new logfile. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the file name is appended with an numeric digit: 1, 2, 3, etc. The default is "4MB". |
| logger.file.maxBackupIndex | (OPTIONAL) The maximum rollover file index. When log files are rolled over, a numeric index is appended to the name, starting with 1 and proceeding to this value. The default is 100. |
| logger.enableConsole | (OPTIONAL) If true all log statements that are sent to the log file are also sent to the console. The default is false. |
| logger.enableDebugFilter | (OPTIONAL) If true all log statements that have the level DEBUG will not be logged. The default is false. |
| logger.verbose | (OPTIONAL) If true
all DEBUG, INFO, WARN, ERROR, and FATAL messages logged will contain the
following format: [INFO ] Sample log message Class Name: com.cafesoft.cams.log.CamsTraceLogger Method Name: info() Line Number: 121 Timestamp: 25 Jul 2002 11:02:36,339 If false ONLY WARNING, ERROR, and FATAL message level will use the verbose format, while DEBUG and INFO level messages will use the following format: [INFO ] Sample Log Message The default is false. |
| logger.debug | (OPTIONAL) If true the logger will output diagnostic debug statements to the System.err stream. The default is false. |
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.
You must add a reference to the Cams Servlet Filter web agent in web.xml for EACH webapp that uses Cams security. Add the filter and filter mapping as shown in Example 1. Make sure that your replace the fully_qualified_path (shown in red in Example 1) with a file path of your choosing to the appropriate cams-webagent.conf file. This is the only value you need to change.
WARNING: The Cams Servlet Filter web agent should be first in the filter chain so that it can determine if access should be granted. If the Cams Servlet Filter web agent fails to load correctly, it will deny access to the web application.
<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 1 - Configuring a web application to use the Cams Servlet Filter web agent |
Filter Values
The distribution cams web application includes four sample Java Server Pages (JSP):
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">
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:
When you click the submit button, the Cams Servlet Filter web agent intercepts the POST to the cams.login.uri and sends the request to the Cams policy server. The request includes the security domain and a login-config-entry, which the Cams policy server 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.
When you request a protected resource that requires authentication and Cams doesn't know your user identity, the Cams Servlet Filter 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 2.
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") %>">
|
| Example 2 - login.jsp example login page |
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 policy 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).
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 3 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>
<% } %> |
| Example 3 - denied.jsp displays any dynamic access denied messages |
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>
<% } %> |
| Example 3 - error.jsp example displays any dynamic error messages |
The Cams Servlet Filter 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 Cams Web Agent Optimizations to learn more about Cams Servlet Filter web agent optimizations.
Before you start the J2EE/Servlet 2.3 server with a Cams Servlet Filter web agent, you'll need to ensure that the Cams policy server knows about it. See Web Agent-specific Cams Policy Server Configuration to learn more about Cams policy server configuration requirements.
That's it, you should now be able to start the J2EE/Servlet 2.3 server to test your Cams Servlet Filter web agent configuration. After you've started both the J2EE/Servlet 2.3 with the Cams Servlet Filter web agent and the Cams policy 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.
© Copyright 1996-2004 Cafésoft LLC. All rights reserved.