Apache 2.0 Web Agent

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

This document provides instructions on how to install and configure the Cams Apache 2.0 web agent, which is an Apache version 2.0.x module available for the following operating systems and hardware architectures:

• RedHat Linux 9 for AMD/Intel x86
• RedHat Linux 8 for AMD/Intel x86
• SUSE Linux Server 8 for AMD/Intel x86
• SUSE Linux Server 7 for AMD/Intel x86
• Windows NT 4.0, Windows 2000, Windows 2003, Windows XP AMD/Intel x86

The Cams Apache 2.0 web agent on Linux supports the prefork Apache 2.0 Multi-Processing Module (MPM). Support for the worker and perchild MPMs is not currently available. On Windows operating systems, the multi-threaded "winnt" Multi-Processing Module is supported. The "winnt" MPM supports Windows NT 4.0, Windows 2000, Windows 2003, and Windows XP. See the Apache 2.0 documentation for more information on MPMs. If you need support for another operating system, hardware architecture, or MPM, please contact Cafésoft support.

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

Installation

These instructions guide you through the installation of the Cams Apache 2.0 web agent on a system with Apache 2.0.x already installed. If Apache is not yet installed, you must first do so. You must also download the Cams Apache web agent. Various Cams Apache 2.0 binaries are available to support different releases of Apache 2.0.x.

To identify your Apache server version, open a Unix shell or Windows console, change directories to the location where Apache 2.0.x binaries are installed and use the following command:

Linux

./httpd -V

Windows

.\Apache.exe -V

Among other information, you should see a line that looks like this:

Server version: Apache/2.0.40

Choose the Cams Apache 2.0 agent version compatible with your Apache installation; the supported Apache version is embedded within the name of the download file.

NOTE: Please contact Cafésoft support if you have questions on supported Apache 2.0.x versions.

Confirming Availability of OpenSSL

The Cams Apache web agent requires the installation of OpenSSL libraries on your system to encrypt sensitive values sent to and received from the Cams policy server. The Cams Apache web agent for Windows ships with OpenSSL libraries, while distributions for UNIX/Linux do not. The following instructions apply only to Linux installations:

Linux

The following command can be used from a Unix command shell to look for existing OpenSSL libraries:

ls -laF /usr/lib/libssl*

If OpenSSL is installed, you should see a listing that looks something like this:

If OpenSSL is not installed in directory /usr/lib, it may be installed in directory /lib. In that case, try the following command:

ls -laF /lib/libssl*

NOTE: On some Unix/Linux installations, /lib is a symbolic link to /usr/lib, so they are the same directory.

Although OpenSSL version 0.9.7 is recommended, patched copies of 0.9.6 may also be used. Check your operating system documenation for OpenSSL compatibility before changing versions. Appropriate symbolic links to available OpenSSL libraries will be setup by the Cams Apache 2.0 installation script if required.

OpenSSL also includes a cryptography library that is needed by the Cams Apache 2.0 web agent. The cryptography library version must be the same as the SSL library version. The following command can be used to confirm its availability:

ls -laF /usr/lib/libcrypto*

or

ls -laF /lib/libcrypto*

If the OpenSSL cryptography library is installed, you should see a listing that looks something like this:

lrwxrwxrwx 1 root other 18 Jan 28 16:40 /usr/lib/libcrypto.so -> libcrypto.so.0.9.7*
-rwxr-xr-x 1 root other 1311816 Feb 10 13:59 /usr/lib/libcrypto.so.0.9.7*

Unpacking Distribution Files

The following instructions assume you are using Apache server version 2.0.40 under Linux or 2.0.49 under Windows. Substitute the appropriate file name for your downloaded Cams Apache 2 web agent distribution.

Linux

You'll need to copy cams-webagent-apache2_0_40-linux-i386-2.0.X.tar.gz to a temporary directory on the target host. You must login as root and navigate to the directory where you copied the cams-webagent-apache2_0_40-linux-i386-2.0.X.tar.gz file and unpack it into the temporary directory.

cd /tmp
gunzip cams-webagent-apache2_0_40-linux-i386-2.0.X.tar.gz
tar xvf cams-webagent-apache2_0_40-linux-i386-2.0.X.tar

Change directories to cams-webagent-apache2_0_40-linux-i386-2.0.X. 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 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/libcscrypto.so.0.9.6
lib/libcscrypto.so.0.9.7
lib/libcscore.so.0

The target directories into which these files are copied may be a function of both the versions of Unix/Linux and Apache you are using. For example, the RedHat Linux 7.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 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

Windows

Unzip cams-webagent-apache2_0_49-win32-2.0.X.zip to a temporary directory on the target host.

The files shown in Figure 2 should have been extracted from the distribution.

<!-- Cams Apache web agent documentation and license -->
README.txt
LICENSE
ReleaseNotes.html
Setup.exe

<!-- Cams Apache web agent libraries -->
cams\mod_cams_apache20_winnt_webagent.so
cams\libcams.dll
cams\libcamsclient_mt_cams_1_0.dll
cams\libcams-common.dll
cams\libcscore.dll
cams\libeay32.dll
cams\ssleay32.dll

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

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

Installing the Agent

On Linux, the Cams Apache 2.0.X web agent is installed using a shell script. On Windows, the Cams Apache 2.0.x web agent includes a Setup.exe file that launches a graphical installer.

Linux

The installation script attempts to find the Apache installation and library directories, 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 directories you specify. To run the installation script, use the following commands:

cd /tmp/cams-webagent-apache2_0_40-linux-i386-2.0.X/
./install-webagent.sh

Follow the prompts to provide required information. After running the installation script, you'll still need to:

1. Edit the cams-webagent.conf file
2. Edit the Apache httpd.conf file
3. Copy/edit Cams Perl scripts (optional)

Windows

Run the Setup.exe program included with the Cams Apache 2.0.x distribution, which will copy files and setup Windows Start menu options. After setup, you'll still need to:

1. Edit the cams-webagent.conf file
2. Edit the Apache httpd.conf file
3. Download/install Perl (optional)
4. Copy/edit Cams Perl scripts (optional)

Cams Web Agent Configuration

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

NOTE: To secure resources on your Apache 2.0 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, as shown in Table 2.

Table 2 - 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 load the module and specify the location of Cams configuration information.

Linux

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 Red Hat 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.

Windows

Open the httpd.conf file for your Apache 2 installation 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 CamsApache20WinntWebAgent_module "C:/cams-webagent-apache2/cams/mod_cams_apache20_winnt_webagent.so"

#
# Specify the Cams Apache web agent home directory.
#
CamsWebAgentHome "C:/cams-webagent-apache2"

Example 2 shows a typical configuration from httpd.conf included with the Apache 2 binary distribution for Windows. 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.
# Statically compiled modules (those listed by `httpd -l') do not need
# to be loaded here.
#
# Example:
# LoadModule foo_module modules/mod_foo.so
#
LoadModule access_module modules/mod_access.so
...

#
# Load Cams Apache web agent module
#
LoadModule CamsApache20WinntWebAgent_module "C:/cams-webagent-apache2/cams/mod_cams_apache20_winnt_webagent.so"

#
# Set the path to the Cams Apache web agent home directory.
#
CamsWebAgentHome "C:/cams-webagent-apache2"
...

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 conflicts, you should disable Apache security specified in httpd.conf for all resources that are 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.

Linux

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 conf
chgrp root conf
chown root conf/cams-webagent.conf
chgrp root conf/cams-webagent.conf
chown root logs
chgrp 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 .
chgrp -R 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 server/Cams web agent 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 permission 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 a default permission 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 enable 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 3.

#!/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 was created in the logs directory with permission 600 (rw-------).

Windows

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

Typically, Apache 2 is started as a Windows service. The general strategy for securing Cams-related configuration files and directories is to:

1. Enable owner read/write/execute permissions on all directories containing Cams files, but no permissions for all other users and groups. This enables owner processes to scan and modify the contents of directories, while prohibiting all other users and groups from seeing or modifying the contents of these directories.
2. Enable owner read/write permissions on configuration files and log files, but no permissions for all other users and groups. This ensures that an arbitrary user cannot replace, overwrite, or redirect log files to obscure security violations or obtain sensitive information via trace logs.

In the instructions that follow, it is assumed that the Apache 2 server is started by Administrator on your Windows NT/2000/2003 system. This example assumes that you are logged in as Administrator to your Windows NT/2000/2003 server.

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

This is done using the Windows NT/2000/2003 graphical user interface.

1. Using the Windows Explorer file browser, select the top-level Cams Apache 2 web agent directory
2. Right click on the folder and select Properties from the pop-up menu
3. In the dialog box that appears, select the Security tab
4. Click on the Ownership button
5. In the dialog box that appears, confirm that Administrators is the intended owner, then click Take Ownership

Step 2 - Set all directory and file permissions

From the same Security tab used in Step 1:

1. Click on the Permissions button
2. In the Directory Permissions dialog box that appears, confirm that the directory owner is Administrators
3. Select check box Replace Permissions on Subdirectories (e.g., make sure it is checked)
4. Select check box Replace Permissions on Existing Files (e.g., make sure it is checked)
5. In the list of all User\Group items listed, Remove all items except Administrator
6. Select the list item Administrator, then select Type of Access as Full Control

Scripts

Cams web agents ship with scripts used for prompting users for username/password, reporting errors, reporting access denied messages, and testing. The scripting languages supported depend on the Apache 2 operating environment and currently include:

• Linux - Shell scripts
• Windows - Perl scripts

The remainder of the instructions are operating system specific.

Linux

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

This script provides a convenient way to test basic operation of your Cams Apache 2 web agent and connectivity to a Cams policy server. It includes an HTML form with values that can be used to attempt authentication with a Cams policy server and will display user session information and Cams HTTP request headers if authentication is successful.

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 2.0 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 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 4.

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 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).

cams-denied.sh

If you are denied access to a resource protected by Cams, the page specified by the cams.denied.url property in cams-webagent.conf is displayed. 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_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 6 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">

Windows

The Cams Apache 2 web agent cgi-bin directory includes four sample Perl shell scripts:

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

Copy the desired scripts from the Cams Apache2 web agent installation directory to your Apache 2 cgi-bin directory.

NOTE: If you do not have Perl installed on your Windows system, we recommend that you download and install ActivePerl from the following site: http://www.activestate.com. If the default installation path is accepted, ActivePerl will install at: C:\Perl. If a different installation path is used, you'll need to edit the first line of each Perl script to indicate the path to your Perl executable. For example: #!C:\Perl\bin\perl

cams-webagent-test.pl

This script provides a convenient way to test basic operation of your Cams Apache 2 web agent and connectivity to a Cams policy server. It includes an HTML form with values that can be used to attempt authentication with a Cams policy server and will display user session information and Cams HTTP request headers if authentication is successful.

You should browse to cams-webagent-test.pl to understand how to configure and use it for testing. The following HTML form parameters are posted to the URI specified by the cams.login.uri property in cams-webagent.conf:

• 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 2.0 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 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.pl

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

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
#
print "  <!-- Populate hidden fields from their request parameters -->\n";
if ($QS_SECURITY_DOMAIN ne "") {
   print "  <input type=\"hidden\" name=\"cams_security_domain\" value=\"$QS_SECURITY_DOMAIN\">\n";
}
else {
   $MISSING_PARAM="true";
   print "  <p class=\"error\">ERROR: Missing required cams_security_domain query parameter</p>\n";
}
       
if ($QS_LOGIN_CONFIG ne "") {
   print "  <input type=\"hidden\" name=\"cams_login_config\" value=\"$QS_LOGIN_CONFIG\">\n";
}
else {
   $MISSING_PARAM="true";
   print "  <p class=\"error\">ERROR: Missing required cams_login_config query parameter</p>\n";
}
   
if ($QS_ORIGINAL_URL ne "") {
   print "  <input type=\"hidden\" name=\"cams_original_url\" value=\"$QS_ORIGINAL_URL\">\n";
}
else {
   $MISSING_PARAM="true";
   print "  <p class=\"error\">ERROR: Missing required cams_original_url query parameter</p>\n";
}

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

cams-denied.pl

If you are denied access to a resource protected by Cams, the page specified by the cams.denied.url property in cams-webagent.conf is displayed. Example 8 shows a script that displays dynamic messages.

#
#---    Parse the QUERY_STRING into standard variables
#
sub parseQueryString {
   $query_string = $ENV{'QUERY_STRING'};
   @queryParameters = split(/&/, $query_string);
   foreach $queryParameter (@queryParameters) {
      ($field_name, $field_value) = split(/=/, $queryParameter);
      if($field_name eq "message") {
         $QS_MESSAGE = $field_value;
         $QS_MESSAGE =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;
      }         
      elsif($field_name eq "reason") {
         $QS_REASON = $field_value;
         $QS_REASON =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;
      }         
      elsif($field_name eq "resourceId") {
         $QS_RESOURCE_ID = $field_value;
         $QS_RESOURCE_ID =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;
      }         
      elsif($field_name eq "resourceActions") {
         $QS_RESOURCE_ACTIONS = $field_value;
         $QS_RESOURCE_ACTIONS =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;
      }         
   }
}

cams-error.pl Example

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

#
#---    Parse the QUERY_STRING into standard variables
#
sub parseQueryString {
   $query_string = $ENV{'QUERY_STRING'};
   @queryParameters = split(/&/, $query_string);
   foreach $queryParameter (@queryParameters) {
      ($field_name, $field_value) = split(/=/, $queryParameter);
      if($field_name eq "message") {
         $QS_ERROR_MESSAGE = $field_value;
         $QS_ERROR_MESSAGE =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;
      }         
   }
}

NOTE: Regardless of the scripting language, 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 Cams Web Agent Optimizations to learn more about Cams Apache 2.0 web agent optimizations.

Cams Policy Server Configuration

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

Testing

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

Linux

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

Windows

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

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-2004 Cafésoft LLC. All rights reserved.