Back | Next | Contents Cams Web Agent Guide

IIS 6 ISAPI Web Agent Integration

This document provides instructions on how to install and configure the Cams IIS web agent on Microsoft Internet Information Server version 6. The Cams IIS web agent is an ISAPI filter and extension for Windows 32-bit or 64-bit systems.

Install the 32-bit web agent on 32-bit Windows operating systems and the 64-bit web agent on 64-bit Windows operating systems. The instructions that follow apply to all supported versions of Windows except where specifically noted. If you are installing on Windows Server 2008 use the instructions for IIS 7. Before proceding with Cams IIS web agent integration, you must first install the web agent files and configure basic settings as described in Cams Web Agent Installation. For known issues with the Cams IIS web agent see ReleaseNotes.html found in the root directory of the Cams IIS web agent distribution.

Configuring the Cams Filter

The Cams IIS web agent is an ISAPI filter and 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.

  1. Right click on on the IIS server where you want to install the Cams IIS web agent and select Restart IIS
  2. 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
  3. 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.

  4. In the window that pops up, select the ISAPI Filters tab
  5. Click Add and enter the filter name cams iis web agent
  6. Click Browse and navigate to the cams_iis_webagent.dll file in the cams subdirectory of the Cams IIS web agent installation
  7. Click OK to close the dialog box and OK to close the web site Properties window
  8. Right click on on the IIS server again and select Restart IIS
  9. 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.

  1. 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
  2. Navigate to New and select Virtual Directory
  3. 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.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. If you plan to use the Cams-provided login.aspx and camstest.aspx pages, you'll need to enable the associated ASP.NET Web Service Extension. If your site already makes use of ASP.NET, then this extension is already enabled.

You can configure these web service extensions by manipulating the web service extensions node in IIS Manager to; 1) Allow or prohibit web service extensions; 2) Add new web service extensions; 3) Allow the web service extensions that a specified application can call, and; 4) 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 Administrator's 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:

  1. Launch the IIS Manager
  2. Expand the local computer
  3. Click Web Service Extensions
  4. In the details pane, click Add a new Web service extension ...
  5. In the dialog box that appears (see Figure 3), type Cams IIS Web Agent for the Extension name
  6. Click Add...
  7. 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
  8. Select the Set extension status to Allowed check box to automatically set the status of the new web service extension to Allowed
  9. 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 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 two sample ASP.NET scripts for user interaction:

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

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

Securing Directories and Files

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:

  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.

The instructions that follow assume that the IIS server is started by Administrator and you are logged in as Administrator.

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

This is done using the Windows user interface.

  1. Using the Windows Explorer file browser, select the top-level Cams IIS 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

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 3 and 4, 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.aspx

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:

  1. The Windows event logger
  2. 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