Cams Web Agent Guide

IIS 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 response, including prompting for user authentication if required.

This document provides instructions on how to install and configure the Cams IIS web agent. The Cams IIS web agent is a Microsoft Internet Information Server version 5 and 6 ISAPI filter and extension for Windows 2000/2003 Server and Windows 2000/XP Professional. The instructions that follow apply to all supported versions of Windows except where specifically noted.

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

Installation

These instructions guide you through the installation of Cams IIS web agent on a Windows system with IIS already installed. If IIS is not yet installed, you must first do so. You must also download the Cams IIS web agent.

The Cams IIS web agent is packaged in a zip file that contains documentation and the Setup.exe installer. Unzip the distribution into a temporary directory of your choice and double click on the Setup.exe file to begin the installation. The distribution files will install by default into:

c:\cams-webagent-iis

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-iis. You must also preserve the Cams IIS web agent subdirectory structure.

You will also be given the option to install convenience Windows Start menu items to view the Cams Web Agent Guide and to open the cams-webagent.conf file. The final installer screen provides options that help you complete the installation:

View the documentation
Edit cams-webagent.conf
Launch the Internet Services Manager

After installing, open the Windows explorer to the directory where your installed the Cams IIS web agent. You should see the files and directories shown in Figure 1.

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

<!-- Cams IIS web agent scripts and dlls files -->
cams\camsclient_mt_cams_3_0.dll
cams\camstest.asp
cams\cams_iis_webagent.dll
cams\libapr.dll
cams\libapriconv.dll
cams\libaprutil.dll
cams\libcams-common.dll
cams\libcams.dll
cams\libcscore.dll
cams\libcsconv_apr_1_0.dll
cams\libeay32.dll
cams\login.asp
cams\ssleay32.dll

<!-- Internationalization/Character conversion libraries -->
cams\iconv\*.so

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

<!-- Cams IIS web agent log file directory -->
logs\

Figure 1 - Directory listing of the Cams IIS web agent files after installation

NOTE: Setup.exe is provided for convenience in copying files, setting up Start menu options and configuring the Cams IIS web agent. You can also unzip the distribution to a directory of your choice and browse to the the configuration file, open the documentation and launch the Internet Services Manager.

Web Agent Configuration

The Cams IIS web agent is configured in the cams-webagent.conf file. In addition, you also need to use the Internet Services Manager to configure a filter and a cams virtual directory. This section describes the configuration requirements.

NOTE: To secure resources on your IIS 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.

Configuring the Cams Filter

The Cams IIS web agent filter is an ISAPI extension responsible for enforcing authentication and access control decisions made by a Cams policy server.

If you have not already done so, launch the Internet Services Manager and expand the tree menu.

Right click on on the IIS server where you want to install the Cams IIS web agent and select Restart IIS
In the window that pops up, change to selection to Stop Internet Service on [name]. Wait for IIS to stop and dismiss the dialog box
Right click on on the target web site and select Properties (if you only have one web site, this may be named Default Web Site)

WARNING: You can only install the Cams ISAPI filter in one location on each IIS web server. If you choose the IIS server-level properties menu, the Cams ISAPI filter will be inherited and protect all virtual hosts. Alternatively, you can install it on a single virtual host. You cannot, however, install the Cams ISAPI filter on multiple, selective virtual hosts within a single IIS web server.
In the window that pops up, select the ISAPI Filters tab
Click Add and enter the filter name cams iis web agent
Click Browse and navigate to the cams_iis_webagent.dll file in the cams subdirectory of the Cams IIS web agent installation
Click OK to close the dialog box and OK to close the web site Properties window
Right click on on the IIS server again and select Restart IIS
In the window that pops up, change the selection to Start Internet Service on [name]. Wait for IIS to start and dismiss the dialog box

After you restart the IIS server, you should check the Cams IIS web agent filter to ensure it is correctly initialized by right clicking on the web site and selecting Properties. When you click the ISAPI Filters tab, you should see a green arrow by the Cams IIS Web Agent filter as shown in Figure 1.

Figure 1 - Cams IIS web agent filter after successful installation

The order in which ISAPI DLLs execute depends on the priority of the filter as well as the order in which it appears in the ISAPI filters property page in Internet Services Manager. A filter's priority can be either high, medium or low. Filters with a higher priority will execute first, while filters with the same priority setting will capture notifications in the order in which they appear in the ISAPI property page. The Cams IIS web agent filter is set to high priority. If the Cams IIS web agent filter is not at the top of a list a filters, select it and use the arrow buttons on the left to move it to the top of the list.

Configuring the Cams Virtual Directory

The Cams IIS web agent virtual directory provides login and test page resources as well as an ISAPI DLL Cams uses for redirects and authentication services.

If you have not already done so, launch the Internet Services Manager and expand the tree menu.

Right click on on the web site to protect with Cams and select Properties. If you only have one web site, this may be named Default Web Site
Navigate to New and select Virtual Directory
Follow the wizard prompts:
1. Set the virtual directory name to cams
2. Click Browse and navigate to the cams_iis_webagent.dll file in the Cams IIS web agent installation directory
3. Select only the Run Scripts and Execute access permissions
4. Click Finish

You should see the cams virtual directory in the Internet Services Manager tree. Right click the cams virtual directory and select Properties. You should see a window similar to the one shown in Figure 2.

Figure 2 - Cams virtual directory configuration

Provided you have already configured a Cams security domain, you should now be ready to test this Cams IIS web agent installation. An self-documented test page is provided in the cams virtual directory that you can use for testing.

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

Adding the Cams Web Service Extension

NOTE: The instructions in this section apply to Windows 2003®/IIS 6.0 only.

With Windows Server 2003/IIS 6.0, Microsoft has taken a more proactive stance against malicious users and attackers. By default, IIS serves only static content — meaning the Cams IIS Web Agent and features like ASP, ASP.NET, Server-Side Includes, WebDAV publishing, and FrontPage® Server Extensions do not work unless enabled.

WARNING: If you do not enable the Cams IIS Web Agent as a Web Service Extension, IIS will return a 404 error when the Cams IIS web agent attempts to authenticate a user.

In addition, the standard Cams IIS web agent login and test pages are Active Server Pages (.asp), which require use of the ASP.DLL Web Service Extension.

WARNING: If you plan to use the Cams-provided login.asp and camstest.asp pages, you'll need to enable the associated ASP Web Service Extension. If your site already makes use of ASPs, then this extension is already enabled.

You can configure these web service extensions, by manipulating the web service extensions node in IIS Manager to allow and prohibit web service extensions. Add new web service extensions. Allow the web service extensions that a specified application can call. Prohibit all web service extensions from running on the local computer. You can enable or disable web service extensions individually if they are registered in the web service extensions node in IIS Manager.

You must be a member of the Administrators group on the local computer to perform the following procedure, or you must have been delegated the appropriate authority.

To enable the Cams IIS Web Agent as an IIS web service extension:

Launch the IIS Manager
Expand the local computer
Click Web Service Extensions
In the details pane, click Add a new Web service extension ...
In the dialog box that appears (see Figure 3), type Cams IIS Web Agent for the Extension name
Click Add...
In the Path to file text field, type the path to the cams-iis-webagent.dll file or click Browse ... to navigate to the directory where you installed the Cams IIS web agent and select the cams-iis-webagent.dll
Select the Set extension status to Allowed check box to automatically set the status of the new web service extension to Allowed
Click OK

Figure 3 shows the settings used to enable a Cams IIS web agent installed in the default location.

Figure 3 - Populating the new web service extension dialog box (Windows 2003/IIS 6.0)

Figure 4 shows the web service extensions pane after the Cams IIS web agent has been added and allowed as a web service extension.

Figure 4 - The web service extensions pane after adding the Cams IIS web agent extension (Windows 2003/IIS 6.0)

WARNING: The Microsoft documentation indicates (in some places) that All Unknown ISAPI Extensions may be allowed (see Figure 4). Although this would enable the Cams IIS web agent extension to execute within Windows 2003/IIS 6.0, it may also enable unknown and untrusted extensions to execute. Consequently, it is not recommended to allow All Unknown ISAP Extensions.

Scripts

The cams virtual directory includes four sample Active Server Pages (ASPs) for user interaction:

camstest.asp - facilitates integration testing
login.asp - 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 web agent to redirect to these pages, see Configuration Properties.

NOTE: The camstest.asp 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.

Securing Directories and Files

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

Typically, IIS 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 IIS 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 IIS 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 IIS server with a Cams IIS 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 IIS to test your Cams IIS web agent configuration. After you've started both IIS with the Cams IIS web agent and the Cams policy server, test the configuration using:

http://[hostname:port]/cams/camstest.asp

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 logs:

The Windows event logger
The Cams web agent cams-webagent.log file (CAMS_IIS_WEB_AGENT_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 Windows event log. In most cases, errors will be cause by a misconfigured Cams virtual host, Cams ISAPI filter 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