| Back | Next | Contents | Cams Web Agent Guide |
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 Servlet Filter web agent. The Cams Servlet Filter web agent is a Java J2EE servlet filter implementation that provides web content security including Java Server Pages, servlets, HTML pages, images, and files 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.
You can download the Cams Servlet Filter web agent by logging into the Cams User Portal. 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-1_2-0.tar.gz or cams-webagent-servletFilter-1_2-0.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-1_2-0.tar.gz
Windows
pkunzip cams-webagent-servletFilter-1_2-0.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 docs/webagent/* <!-- 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 container-specific instructions are not available for the J2EE server you are using, try following the container neutral steps specified above. If you have difficulties, please contact Cafésoft support with the J2EE container 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 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 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 4.1.x perform the following steps:
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, error, and denied 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, error, and denied 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 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.server.url |
The URL of the Cams Server to be used by this agent. The 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 server communicate through a firewall, the firewall must be configured to allow general TCP/IP traffic on the configured Cams server port. |
| cams.server.name | The name of the Cams server to which this agent will delegate requests. This value is used to identify Cams session cookies originating from a Cams server installation. |
| cams.debug |
Toggle on/off debug messages. WARNING: Turning on debug can have an adverse affect on 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 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 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, servlet, JSP, or script 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 server response for a specified period of time. |
| cams.access.check.cache.size | The maximum number of access control responses that can be cached at a given time. |
| cams.access.check.cache.refreshTime | The amount of time, in minutes, that is allowed before an access control request is sent to the server to check if the cache should be cleared. |
| cams.session.cache | Enable/disable session caching. Session caching enables the servlet API and cgi-bin applications to access Cams session attributes such as HTTP request header values. |
| cams.http.headers | Enable/disable setting of Cams HTTP request headers. If enabled, then 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.client.authentication.type |
The type of authentication the Cams Servlet Filter web agent will use to authenticate connections that it establishes with the Cams server. Currently supported types include:
NOTE: This is NOT the authentication type used to authenticate users, it is the type used to authenticate the agent. |
| cams.client.authentication.principal | The principal (or username) the Cams Servlet Filter web agent will use to authenticate connections it establishes with the Cams server. |
| cams.client.authentication.credential | The credential (or password) the Cams Servlet Filter web agent will use to authenticate connections it establishes with the Cams server. |
| cams.client.authentication.timeout | The maximum time (in seconds) that the webagent will wait for a response from the Cams server. If a response has not been returned by the Cams Server within the allotted timeout period authentication fails. |
|
cams.skey.algorithm |
Secret key parameters used for selective encryption/decryption of communications with the Cams server.
For more information, see: the Cams Administrator's Guide - Securing Cams Communications using Secret Keys. |
| logger.class | (REQUIRED) The fully qualified Java classname of the Logger to use. |
| 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 value is true. |
| logger.file.bufferSize | (OPTIONAL)Indicates the size of the buffer to fill before writing to the log file. The default value 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 maxSize value 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 maxBackupIndex 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 value is false. |
| logger.enableDebugFilter | (OPTIONAL) If true all log statements that have the level "DEBUG" will not be logged. The default value 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 value is false. |
| logger.debug | (OPTIONAL) If true the logger will output diagnostic debug statements to the System.err stream. The default value 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 are now ready to configure your web applications to use the Cams Servlet Filter web agent by adding a reference to the Cams Servlet Filter web agent to web.xml for EACH webapp that uses Cams security. Add the filter and filter mapping as shown in Example 1.
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 |
This example shows that configuration divided into filter and filter mapping element groups.
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 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.
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 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 the following documentation regarding available Cams web agent optimizations: Cams 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 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.
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 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-2003 Cafésoft LLC. All rights reserved.