Cams Web Agent Guide

Apache 2.0 Windows Web Agent Integration

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 Windows web agent, which is an Apache version 2.0 module available for:

Windows 2000/2003 Server
Windows 2000/XP Professional

The Cams Apache 2.0 Windows web agent supports the multi-threaded winnt Multi-Processing Module (MPM). 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 Windows web agent, see ReleaseNotes.html found in the root directory of the Cams Apache 2.0 Windows web agent distribution.

Installation

These instructions guide you through the installation of the Cams Apache 2.0 Windows 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.

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

.\Apache.exe -V

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

Server version: Apache/2.0.52
Server built: Jan 6 2005 10:33:13
Server's Module Magic Number: 20020903:9
Architecture: 32-bit
...

Your Apache 2 server version is compatible with the Cams Apache 2 web agent distribution if the server version starts with 2.0. (e.g. 2.0.50, 2.0.53, etc.) and the major part of the Magic Number (20020903) matches exactly. It's OK if the minor part of the magic number (the part after the colon character) differs for your server. If your Apache 2 server Magic Number is different, contact Cafésoft support to determine if another Cams web agent distribution is available for your environment.

Confirming Availability of OpenSSL

The Cams Apache 2.0 Windows 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 2.0 Windows web agent includes the required OpenSSL libraries with the distribution.

Unpacking Distribution Files

The following instructions assume you are using Apache server version 2.0.52. Substitute the appropriate file name for your downloaded Cams Apache 2.0 Windows web agent distribution.

Unzip cams-webagent-apache2_0_52-win32-2.1.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\libcamsclient_mt_cams_2_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\camstest.pl

Figure 2 - Directory listing of the Cams Apache 2.0 Windows web agent files after unpacking

Installing the Agent

The Cams Apache 2.0 Windows web agent includes a Setup.exe file, which will copy files and setup Windows Start menu options.

WARNING: The installer defaults to the drive Windows is installed on (typically c:). You can install to another directory, however, you MUST use a directory path that does NOT contain any spaces. For example, do NOT use C:\Program Files\cams-webagent-apache. You must also preserve the Cams Apache 2.0 web agent subdirectory structure.

After you run Setup.exe, you'll still need to:

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

Cams Web Agent Configuration

The Cams Apache 2.0 Windows 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 Windows 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. You can also reference more detailed information on the properties in the Configuration Properties document.

NOTE: The most important properties are at the top of cams-webagent.conf. In most cases, the default property values will work if the Cams policy server and Cams web agent are on the same host. As you begin to integrate more web and application servers, reference Configuration Properties to understand the properties that will usually be the focus of your attention.

Editing 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 2.0 Windows web agent module requires the insertion of two lines that load the module and specify the location of Cams configuration information.

Open the httpd.conf file for your Apache 2.0 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 after the module loading and adding sections:

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

Example 2 - The Apache 2.0.x httpd.conf file after registering the Cams Apache 2.0 Windows web agent module

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 2.0 Windows 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.

Scripts

The distribution cgi-bin directory includes four sample Perl scripts:

camstest.pl - facilitates integration testing
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

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

NOTE: The camstest.pl page is extremely useful for integration testing. You use it to quickly confirm correct Cams web agent communications with a Cams policy server, validate authentication configuration and determine if expected user session values are available in the web environment for authenticated users.

Copy the desired scripts from the Cams Apache 2.0 Windows web agent installation directory to your Apache 2.0 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

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.

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 is started as a Windows service. The general strategy for securing Cams-related configuration files and directories is to:

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

Using the Windows Explorer file browser, select the top-level Cams Apache 2 web agent directory
Right click on the folder and select Properties from the pop-up menu
In the dialog box that appears, select the Security tab
Click on the Ownership button
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:

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

Cams Policy Server Configuration

Before you start the Apache server with a Cams Apache 2.0 Windows web agent, you'll need to ensure that the Cams policy server knows about it. See the Cams Administrator's Guide - Integration Quick Start to learn more. Pay close attention during integration to steps 4 and 5, which provide information on the settings that must be configured correctly for a Cams web agent to connect to a Cams policy server. You'll need to configure an access control policy corresponding to your site requirements.

Testing

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

http://[hostname:port]/cgi-bin/camstest.pl

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

Debugging

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

The Apache 2.0 web server errors log file (APACHE_HOME/logs/error_log)
The Cams web agent cams-webagent.log file (APACHE_HOME/logs/cams-webagent.log)

During Cams web agent integration, it is helpful to set the following values in cams-webagent.conf:

cams.debug=true
cams.cluster.debug=true

If the Cams web agent is successfully loaded and initialized, verbose DEBUG messages will be logged to cams-webagent.log. If the Cams web agent fails to load or initialize, errors will be reported in the APACHE_HOME/logs/error_log file. In most cases, errors will be cause by misconfigured values in httpd.conf and/or cams-webagent.conf.

WARNING: Remember to disable all Cams web agent debug flags for production environments. Leaving them enabled will decrease performance and result in very large log files.

Back | Next | Contents