Apache 2.0 Web Agent

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 Apache 2.0 web agent. The Cams Apache 2.0 web agent is an Apache version 2.0.x module for Linux/Intel systems. A separate Cams web agent is available for Apache 1.3 on Linux/Intel systems. If you need support for Apache 2.0 on another operating system or hardware architecture, please contact Cafésoft support.

The Cams Apache 2.0 web agent supports the "prefork" Apache 2.0 Multi-Processing Module (MPM). Support for the "worker" and "perchild" MPMs is not currently available. See the Apache 2.0 documentation for more information on MPMs. Please contact Cafésoft support if support for the worker or perchild MPM is needed.

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

Installation

These instructions guide you through the installation of Cams Apache 2.0 web agent on a system with Apache 2.0.x already installed. If Apache 2.0 is not yet installed, you must first do so. You must also download the Cams Apache 2.0 web agent by logging into the Cams User Portal. Multiple binary versions may be available to support different versions of Apache 2.0, so be sure to choose the one most appropriate for your Apache 2.0 web server installation. To see the version and options used when your Apache 2.0 server was compiled, enter:

httpd -V

NOTE: The Cams Apache web agent requires the installation of OpenSSL libraries on your system to encrypt sensitive values sent to the Cams server. If OpenSSL is not installed (most Linux distributions include OpenSSL), you will need to do so before proceeding. Please consult the documentation that came with your Linux distribution for installation instructions.

These instructions assume you are using version 2.0.40 of the Apache 2.0 server. You'll need to copy cams-webagent-apache2_0_40-linux-i386-1.0-1.tar.gz to a temporary directory on the target host. You must have root privileges to install Cams. Login as root and navigate to the directory where you copied the cams-webagent-apache2_0_40-linux-i386-1.0-1.tar.gz file and unpack it into the temporary directory.

cd /tmp
gunzip cams-webagent-apache2_0_40-linux-i386-1.0-1.tar.gz
tar xvf cams-webagent-apache2_0_40-linux-i386-1.0-1.tar

Change directories to the directory cams-webagent-apache2_0_40-linux-i386-1.0-1. The files shown in Figure 1 should have been extracted from the distribution.

<!-- Cams Apache web agent documentation and license -->
README.txt
LICENSE
ReleaseNotes.html
install-webagent.sh

<!-- Cams Apache web agent cgi-bin files -->
cgi-bin/cams-denied.sh
cgi-bin/cams-error.sh
cgi-bin/cams-login.sh
cgi-bin/cams-webagent-test.sh

<!-- Cams Apache web agent configuration files -->
conf/cams-webagent.conf  
conf/webagent.properties
conf/access-control.properties

<!-- Cams Apache web agent documentation -->
docs/webagent/*

<!-- Cams Apache web agent libraries -->
lib/mod_cams_apache20_prefork.so
lib/libcams.so.0
lib/libcamsclient_mt_cams_1_0.so.0
lib/libcams-common.so.0
lib/libcscore.so.0

You can either run the installation script or copy the files to the correct directories on the installation system. The target directories may be a function of both the versions of Linux and Apache 2.0 you are using. For example, the RedHat Linux 9.x RPM installs:

/etc/httpd/conf - the Apache configuration files
/etc/httpd/conf - the Apache modules
/var/www/cgi-bin - the Apache cgi-bin scripts
/var/www/html - the web pages

However, the standard Apache.org installation would have directories:

/usr/local/apache2/conf - the Apache configuration files
/usr/local/apache2/modules - the Apache modules
/usr/local/apache2/cgi-bin - the cgi-bin scripts
/usr/local/apache2/htdocs - the web pages

The following installation section uses the RedHat 9.x directory structure. Please substitute your Apache installation's directories as required.

Cams Web Agent Libraries

The installation script attempts to find the directories listed above, sometimes with your help. It then removes or backs up any previous Cams Apache web agent files it finds and copies the new files to the target locations you specify. If you want to run the installation script, do it now and skip to the Web Agent Configuration section:

cd /tmp/cams-webagent-apache2_0_40-linux-i386-1.0-1/
./install-webagent.sh

To manually install, first copy the module libraries libcams.so.0, libcamsclient_mt_cams_1_0.so.0, libcams-webagent.so.0, libcams-common.so.0 and libcscore.so.0 to /usr/lib:

cd /tmp/cams-webagent-apache2_0_40-linux-i386-1.0-1/lib
cp lib* /usr/lib

Create a symbolic link for each of the libraries of the form library_name.so that points to each library
above:

cd /usr/lib
ln -s libcams.so.0 libcams.so
ln -s libcamsclient_mt_cams_1_0.so.0 libcamsclient_mt_cams_1_0.so
ln -s libcams-common.so.0 libcams-common.so
ln -s libcscore.so.0 libcscore.so

Cams Web Agent Module

Copy the Cams cgi-bin scripts to Apache's cgi-bin directory and make sure that the files have the permissions required for execution. You can look at other working cgi-bin scripts to see the required permissions on your server. Note that the cgi-bin user and group permissions are configured in Apache's httpd.conf file.

cd /tmp/cams-webagent-apache2_0_40-linux-i386-1.0-1/cgi-bin
chown apache.apache *
chmod 755 *
cp * /var/www/cgi-bin

Copy the Cams Apache module mod_cams_apache20_prefork.so to Apache's module directory:

cd /tmp/cams-webagent-apache2_0_40-linux-i386-1.0-1/lib
cp mod_cams_apache20_prefork.so /etc/httpd/modules

Copy cams-webagent.conf and other configuration files to Apache's configuration directory:

cd /tmp/cams-webagent-apache2_0_40-linux-i386-1.0-1/conf
cp cams-webagent.conf /etc/httpd/conf
cp access-control.properties /etc/httpd/conf
cp webagent.properties /etc/httpd/conf

Web Agent Configuration

The Cams Apache 2.0 web agent is configured in the cams-webagent.conf file. However, you'll also need to edit Apache's httpd.conf file and integrate Cams login, error, and denied pages.

NOTE: To secure resources on your Apache 2.0 server, you'll also need to configure a Cams security domain. See the Cams 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, as shown in Table 1.

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.

Editing httpd.conf

You are now ready to edit Apache's httpd.conf file. Before proceeding, make sure that Apache is correctly working on the installation system by starting the server and browsing to a test page. If not, see the Apache documentation for troubleshooting. Before making changes to httpd.conf, you should backup your existing file.

The integration of the Cams Apache web agent module requires the insertion of two lines that add and load the module. Open the /etc/httpd/conf/httpd.conf file in a text editor and navigate to the Dynamic Shared Object (DSO) Support section where the modules are loaded. Then, add the following lines at the end of the module loading section:

#
# Load Cams Apache web agent module
#
LoadModule CamsApache20PFWebAgent_module modules/mod_cams_apache20_prefork.so

The next section is typically where you add the modules. At the end of this section, add the following lines:

#
# Specify the Cams Apache web agent configuration file filepath.
#
CamsWebAgentConfigFile /etc/httpd/conf/cams-webagent.conf

Example 1 shows and typical configuration from httpd.conf included with RedHat 9.0. The inserted lines are in red.

#
# Dynamic Shared Object (DSO) Support
#
# To be able to use the functionality of a module which was built as a DSO you
# have to place corresponding `LoadModule' lines at this location so the
# directives contained in it are actually available _before_ they are used.
# Please read the file http://httpd.apache.org/docs/dso.html for more
# details about the DSO mechanism and run `httpd -l' for the list of already
# built-in (statically linked and thus always available) modules in your httpd
# binary.
#
# Note: The order in which modules are loaded is important.  Don't change
# the order below without expert advice.
#
# Example:
# LoadModule foo_module modules/mod_foo.so

...

<IfDefine HAVE_PUT>
LoadModule put_module modules/mod_put.so
</IfDefine>
<IfDefine HAVE_PYTHON>
LoadModule python_module modules/mod_python.so
</IfDefine>
#
# Load Cams Apache web agent module
#
LoadModule CamsApache20PFWebAgent_module modules/mod_cams_apache20_prefork.so

...

<IfDefine HAVE_SSL>
AddModule mod_ssl.c
</IfDefine>
<IfDefine HAVE_PUT>
AddModule mod_put.c
</IfDefine>
<IfDefine HAVE_PYTHON>
AddModule mod_python.c
</IfDefine>

#
# Set the absolute paths to the configuration file.
#
CamsWebAgentConfigFile /etc/httpd/conf/cams-webagent.conf

...

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 2.0 web agent installation. A self-documented test page is provided in the cgi-bin directory that you can use for testing.

NOTE: Due to the large number of Apache modules, testing all combinations of module loading is impossible. If you experience difficulty loading the Cams Apache web agent module, try changing the module loading order.

WARNING: To avoid security policy conflict, you should remove native Apache security from resources protected by Cams.

Securing Directories and Files

If you have not done so already, you should secure important Apache configuration and log directories and files which may contain Apache SSL certificates, configuration files containing passwords or secret keys, and log files containing sensitive information.

In most cases, the Apache 2.0.x web server process is started under root user ownership and creates child processes that run as another user, like: apache or nobody. Generally, the original process opens and reads configuration files and sockets, then forks a child process to handle requests. Each child process inherits the open file descriptors created by the parent process, so they are able to write to logs files, sockets, etc. The configuration file APACHE_HOME/conf/cams-webagent.conf file is read by mod_cams_apache20_prefork within the parent process and the log file APACHE_HOME/logs/cams-webagent.log is also created by the Apache parent process and inherited by children.

In the instructions that follow, it is assumed that the Apache server is executed by root on your Linux/UNIX system. This example assumes that:

1. Apache is installed at /etc/httpd
2. The Apache configuration directory is at: /etc/httpd/conf
3. The Apache log directory is at: /etc/httpd/logs
4. 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 /, /etc, and /etc/httpd are only modifiable by root. When you install the Apache server, you should ensure that it is similarly protected.

The following steps secure the directories and files relevant to Cams in the Apache environment:

Step 1 - Change directories to the Apache server installation directory

cd /etc/httpd

Step 2 - Set user and group ownership of all files and directories

chown root.root conf
chown root.root conf/cams-webagent.conf
chown root.root logs

This command sets user and group ownership to root.

NOTE: You may consider setting the ownership of all files within the Apache installation tree to root using the following command:

chown -R root.root .

Step 3 - Set directory permissions

chmod 700 conf
chmod 700 logs

This command gives read/write/execute permissions only for the owner (root). No other users or groups are given permissions on these directories, so they will unable to view or modify their contents.

Step 4 - Set file permissions

chmod 600 conf/cams-webagent.conf
chmod 600 logs/cams-webagent.log (Use only if this file exists)

These commands gives them read/write permissions for the owner (root). No other users or groups are given permission to read or write these files.

Step 5 - Set Apache startup/shutdown script umask

To further secure your Apache/Cams webagent installation, you may consider setting file creation permissions so that only root may read/write log files. This is desireable if log files (like the cams-webagent.log file) contain sensitive DEBUG-level information or to avoid hackers from replacing log files or setting up symbolic links that can redirect the contents of log files.

Under Unix, newly created files (e.g. Apache log files) are given default permissions which are a combination of: 666 (read/write permission for everybody) and the currently-set file creation mask (called the umask). The umask is combined with permissions: 666 to take away permissions that might otherwise be granted. By setting the umask value for the shell that executes Apache, log files that are created can be given default permissions: 600, which enables the owner (root) to read/write to them, but denies permissions to all other users.

Generally, Unix user accounts setup a default umask of 022, which results in newly created file permissions of 644. This permission value still enables group and world users to read a file, which is not desireable with sensitive log files. Using umask value: 077 will cause newly created files to be given the desired permissions: 600.

If the Apache web server is started using the shell script at:

/etc/init.d/httpd

You can set the umask for the associated shell by inserting a command at the top of the script as shown in Example 2.

#!/bin/sh
#
# Startup script for the Apache Web Server
#
# chkconfig: - 85 15
# description: Apache is a World Wide Web server.  It is used to serve \
#              HTML files and CGI.
# processname: httpd
# pidfile: /var/run/httpd.pid
# config: /etc/httpd/conf/access.conf
# config: /etc/httpd/conf/httpd.conf
# config: /etc/httpd/conf/srm.conf

# Source function library.
. /etc/rc.d/init.d/functions

# This will prevent initlog from swallowing up a pass-phrase prompt if
# mod_ssl needs a pass-phrase from the user.
INITLOG_ARGS=""

# Path to the apachectl script, server binary, and short-form for messages.
apachectl=/usr/sbin/apachectl
httpd=/usr/sbin/httpd
prog=httpd
RETVAL=0

umask 077

...

To test these file and directory permissions:

1. If the Unix system hosting Cams supports normal user accounts, try logging in as a normal user.
2. Try to list the contents of /etc/httpd/logs (permission should be denied)
3. Try changing directories to /etc/httpd/logs (permission should be denied)
4. Try creating a test file in /etc/httpd/logs/test.txt using a text editor (permission should be denied)
5. To test file creation permissions, login as root. If file /etc/httpd/logs/cams-webagent.log exists, remove it. Then start the Apache web server and confirm that the cams-webagent.log file created in the logs directory has permission: 600 (rw-------).

Scripts

The distribution cgi-bin directory includes four sample Bourne/Bash shell scripts:

• cams-webagent-test.sh - enables lazy and proactive authentication and access control testing, displays context sensitive information for authenticated users
• cams-denied.sh - displays an access denied page if access to a resource request is denied
• cams-error.sh - displays an error page if an authentication or resource request error occurs
• cams-login.sh - displays a login page if a protected resource request is made and the user's identity is not known

cams-webagent-test.sh

You should browse to cams-webagent-test.sh 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:

• cams_cb_username - the username
• cams_cb_password - the user password
• cams_security_domain - the login security domain
• cams_login_config - the security domain's login-config-entry to use
• cams_original_url - The URL to redirect to after successful authentication and authorization

When you click the submit button, the Cams Apache 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.sh.

cams-login.sh

When you request a protected resource that requires authentication and Cams doesn't know your user identity, the Cams Apache 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 cams-index.sh, except that the hidden values are dynamically populated as shown in Example 3.

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=\"securityDomain\" value=\"${QS_SECURITY_DOMAIN}\">
<input type=hidden name=\"loginConfig\"    value=\"${QS_LOGIN_CONFIG}\">
<input type=hidden name=\"originalUrl\"    value=\"${QS_ORIGINAL_URL}\">

The difference between cams-webagent-test.sh and cams-login.sh 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).

cams-denied.sh

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 4 shows a script that displays dynamic messages.

#
#---    Parse the QUERY_STRING into standard variables
#
doParseQueryString ()
{
  #---    Parse into name=value pairs
  for pair in `echo -e ${QUERY_STRING//&/'\n'}`
  do
    #---    Parse the name and value
    name=`echo ${pair} | cut -d'=' -f1`
    value=`echo ${pair} | cut -d'=' -f2`

    #--- Decode + to space, Hex values into character values
    #--- Assign expected query parameters to global variables
    tmp=`echo ${name} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
    decodedName=`printf "${tmp}"`
    if [ "${decodedName}" = "message" ] ; then
      tmp=`echo ${value} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
      QS_MESSAGE=`printf "${tmp}"`
    fi
    done
}

cams-error.sh Example

If an error occurs, Cams displays the page specified by the cams.error.url property in cams-webagent.conf. Example 5 shows a script that displays dynamic messages.

#
#---    Parse the QUERY_STRING into standard variables
#
doParseQueryString ()
{
  #---    Parse into name=value pairs
  for pair in `echo -e ${QUERY_STRING//&/'\n'}`
  do
    #---    Parse the name and value
    name=`echo ${pair} | cut -d'=' -f1`
    value=`echo ${pair} | cut -d'=' -f2`

    #--- Decode + to space, Hex values into character values
    #--- Assign expected query parameters to global variables
    tmp=`echo ${name} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
    decodedName=`printf "${tmp}"`
    if [ "${decodedName}" = "message" ] ; then
      tmp=`echo ${value} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
      QS_ERROR_MESSAGE=`printf "${tmp}"`
    fi
    done
}

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">

Optimizations

The Cams Apache 2.0 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.

Cams Server Configuration

Before you start the Apache server with a Cams Apache 2.0 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.

Testing

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

http://[hostname:port]/cgi-bin/cams-webagent-test.sh

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

Back | Next | Contents

© Copyright 1996-2003 Cafésoft LLC. All rights reserved.