Back | Next | Contents Cams Web Agent Guide

IIS 7 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 7. 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 2003 or XP use the instructions for IIS 6. 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.

Integration Overview

Integrating the Cams IIS web agent on IIS 7 involves the following major steps:

1. Adding IIS Web Server "Service Roles"

You'll make sure all the service role (features) needed by the web agent are installed including support for ISAPI filters, ISAPI extensions and ASP.NET.

2. Configure the Web Agent ISAPI Filter

Here you configure the IIS web server with the Cams web agent ISAPI filter DLL and set its order of execution. ISAPI is the Internet Services Application Programmer's Interface, which is used to extend server functionality. Though IIS 7 now prefers the HttpModule API, it supports and uses ISAPI to implement many features.

The Cams IIS web agent uses the ISAPI filter API to gain access to HTTP requests and to provide access control based on decisions made on a Cams policy server.

3. Configure the Web Agent ISAPI Extension

The Cams IIS web agent DLL is also an ISAPI Extension, which can read HTTP POST data and to provide HTTP responses to errors and other conditions. You'll need to register the ISAPI extension with IIS and set permissions to enable execution here.

4. Configure Handler Mappings for the "cams" ISAPI DLL

You'll need to allow .dll files to execute in the IIS environment. The ISAPI-dll handler is configured to enable Execute permission.

5. (optional) Configure the Cams ISAPI dll to run on 64-bit Windows

If the desired Windows platform IIS is running on is 64-bit, and you need to use the 32-bit Cams IIS web agent, you must configure the application pool in which the Cams ISAPI dll executes to run in the WOW64 (Windows 32-bit On Windows 64-bit) subsystem.

NOTE: We recommend you use the 64-bit Cams IIS web agent on 64-bit Windows.

6. Configure the "cams" Application

In addition to providing access to the web agent ISAPI Extension for Cams login, the cams application also provides the login page and a Cams test page. The cams application is added to the IIS Default Web Site, but may be be used by any/all virtual hosts configured within IIS.

7. Test the "cams" Application and Web Agent

You use the camstest.aspx page to confirm that the Cams IIS web agent is configured correctly to connect to a Cams policy server, authenticate users and access Cams session cookie and HTTP request header data.

Step-by-Step Integration Instructions

This section provides step-by-step instructions for configuring the Cams IIS web agent in the IIS 7 environment. You should have already installed IIS by adding the Web Server role. If not, please consult your Windows 2008 Server documentation to install IIS before proceeding.

Step 1 - Adding IIS Web Server "Service Roles"

To add the IIS service roles (features) needed by the Cams web agent:

  1. Select the Windows "Start" menu and open the "Control Panel".
  2. Double click on the "Programs and Features" icon.
  3. In the "Tasks" panel, select "Turn Windows features on or off". This will display the "Server Manager" window.
  4. Expand the "World Wide Web Services" tree node.

You should see the controls shown in Figure 1.

Figure 1 - Adding features (role services) needed by the Cams IIS web agent

  1. Select the "ASP.NET", ".NET Extensibility", "ASP", "ISAPI Extensions", and "ISAPI Filters" services roles as shown in Figure 2.
  2. If a dialog box appears telling you that a selection has other dependencies, confirm those dependencies should also be installed.
  3. Select the "Next >" button.

Figure 2 - After adding role services needed by the Cams IIS web agent

  1. The service roles/features to be installed are displayed as shown in Figure 3.
  2. Confirm the selected role services should be installed by clicking "Install".
  3. Wait while the IIS configuration is changed. This can sometimes take several minutes, so be patient.

Figure 3 - After confirming role services needed by the Cams IIS web agent

  1. The roles services installation results are displayed as shown in Figure 4.
  2. Select "Close" to close the "Add Roles Services" window.

Figure 4 - Installation results after role services needed by the Cams IIIS web agent have been added

  1. In the "Server Manager" window, confirm that the "ASP.NET", ".NET Extensibility", "ASP", "ISAPI Extensions", and "ISAPI Filters" features are installed as shown in Figure 5.

Figure 5 - The Server Manager after role services needed by the Cams IIS web agent are added to IIS

The IIS Web Server is now ready for Cams IIS web agent integration.

Step 2 - Configure the Web Agent ISAPI Filter

  1. Start the IIS Manager. If the IIS Manager was running during Step 1, restart it.
  2. In the "Connections" pane, select the IIS server "Home" node. If necessary, select the "Features View" at the bottom of the IIS Manager window. You should see GUI controls like those shown in Figure 6.
  3. Confirm that icons for "Handler Mappings", "ISAPI and CGI Restrictions", and "ISAPI Filters" are present. If they are not, then you probably have not selected the top-level IIS Server "Home" node, so select it now. If the icons are still not present, try restarting IIS Manager and if they still are not present, then return to Step 1.
  4. Double click on the "ISAPI Filters" icon.

Figure 6 - The IIS Server Features available for IIS Home

  1. The "ISAPI Filters" pane will display the currently installed filters as shown in Figure 7. NOTE: Your list may vary depending on the service roles and other products or services that you've installed.
  2. If the "cams-iis-webagent" filter is not present in the list, select "Add..." in the "Actions" pane. The "Add ISAPI Filter" dialog box will be displayed. If the "cams-iis-webagent" filters is already present, then skip the "Add..." sub-step.

Figure 7 - The available ISAPI Filters before the Cams IIS web agent ISAPI filter is added

  1. In the "Filter name" field, enter "cams-iis-webagent".
  2. In the "Executable" field, browse to and select the "cams_iis_webagent.dll" file. The field values should look like those in Figure 8.
  3. Select "OK" to add the filter.

Figure 8 - After the Cams IIS web agent .dll has been added as an ISAPI filter

The cams-iis-webagent ISAPI filter should now be displayed in the "ISAPI Filters" pane, but it needs to be executed before other filters because it handles access control and authentication for the content provided by the other filters.

  1. To ensure the Cams filter is executed first, select "View Ordered List..." in the "Actions" pane, then click on the "cams-iis-webagent" filter entry and the "Move Up" action until it is at the top as shown in Figure 9.

Figure 9 - After the Cams IIS web agent ISAPI filter has been moved up to the top of the filter execution order

You are now done adding the Cams ISAPI filter.

Step 3 - Configure the Web Agent ISAPI Extension

  1. In the "Connections" pane, select the top level server node to display all available features.
  2. Double click on the "ISAPI and CGI Restrictions" icon.
  3. In the "Actions" pane, select "Add...". The dialog box shown in Figure 10 is displayed.
  4. Using the browse button "...", browse to and select the cams_iis_webagent.dll file.
  5. In the "Description" field, enter "Cams IIS Web Agent".
  6. Select the "Allow extension path to execute" check box.
  7. Select the "OK" button.

Figure 10 - Adding the Cams IIS web agent DLL as an ISAPI Extension

  1. Confirm the "Cams IIS Web Agent" ISAPI Extension is displayed as shown in Figure 11 in the "ISAPI and CGI Restrictions" pane and is "Allowed".

Figure 11 - After the Cams IIS web agent DLL has been allowed to execute as an ISAPI Extension

The Cams IIS web agent ISAPI Extension has now been added and is allowed to run in IIS.

Step 4 - Configure Handler Mappings for the "cams" ISAPI DLL

This step is required to allow .dll files to execute in the IIS environment. The "ISAPI-dll" handler is configured to enable "Execute" permission.

  1. In the "Connections" pane, select the top level server node to display all available features.
  2. Double click on the "Handler Mappings" icon.
  3. In the "Handler Mappings" pane, select the "ISAPI-dll" mapping. NOTE: This is likely in the "Disabled" list of mappings.
  4. In the "Actions" pane, select "Edit...". The "Edit Script Map" diagram shown in Figure 12 will be displayed.
  5. In the "Request path" field, confirm value "*.dll" is entered.
  6. In the "Excecutable" field, select the file browse button "..." and select the cams_iis_webagent.dll.

Figure 12 - Editing the script map for ISAPI-dlls

  1. In the "Mapping" tab: select the "Request Restrictions" button. The dialog box shown in Figure 13 will be displayed.
  2. Select the check box for "Invoke handler only if request is mapped to" and the "File or folder" choice button.

Figure 13 - Setting the "Mapping" for ISAPI DLLs

  1. In the "Verbs" tab, select "All verbs".

Figure 14 - Enabling use of all verbs (GET, POST, HEAD, etc) for ISAPI DLLs

  1. In the "Access" tab, select "Execute".

Figure 15 - Setting "Execute" access for ISAPI DLLs

  1. Select the "OK" button. The dialog box shown in Figure 16 will be displayed.

Figure 16 - The "Edit Script Map" confirmation dialog box

  1. Select "Yes" to allow the script map edits.
  2. In the Actions pane, select "Edit Feature Permissions...".
  3. In the "Edit Feature Permissions" dialog box, "Set "Execute" permissions for the "cams" application as shown in Figure 17.

Figure 17 - The "cams" application with "Read", "Script", and "Excecute" permissions enabled

  1. In the "Handler Mappings" pane, the "ISAPI-dll" entry should now be "Enabed" for "File or Folder" as shown in Figure 18.

Figure 18 - Handler Mappings with the ISAPI-dll "Enabled" for "File or Folder"

Changes to "Handler Mappings" are now complete.

Step 5 - (optional) Configure the Cams ISAPI dll to run on 64-bit Windows

NOTE: We recommend you use the 64-bit Cams IIS web agent on 64-bit Windows.

If you are running the 32-bit Cams IIS web agent on 64-bit Windows, you'll need to configure the application pool in which the Cams ISAPI dll executes for 32-bit support.

  1. In the "Connections" pane, select "Application Pools". You should the "Application Pools" display as shown in Figure 19.
  2. Select the "DefaultAppPool", by default. If you have configured the Cams ISAPI dll to execute in a different application pool, select it instead.

Figure 19 - Selecting the DefaultAppPool to edit the associated "Advanced Settings..."

  1. With the "DefaultAppPool" highlighted, in the "Actions" pane select "Advanced Settings...". You should see the "Advanced Settings" dialog box shown in Figure 20.
  2. In the "Advanced Settings" dialog, select "Enable 32-Bit Applications", set to "True" as shown in Figure 20 and select "OK" to dismiss the dialog box.

Figure 20 - Selecting the defaultHandler Mappings with the ISAPI-dll "Enabled" for "File or Folder"

Step 6 - Configure the "cams" Application

The "cams" application is responsible for hosting the login page, a test page, and for handling Cams login requests.

  1. In the "Connections" pane, expand the "Sites" folder.
  2. Right click on the "Default Web Site" and select the "Add Application..." menu item. The dialog box shown in Figure 21 will be displayed.
  3. In the "Add Application" dialog box, enter "cams" in the "Alias" field.
  4. In the "Physical Path" field, browse to and select the "cams" directory where the cams_iis_webagent.dll file is installed.
  5. Select the "OK" button to add the application.

NOTE: By default, the application will be configured to use "Pass-through authentication", which supports "Anonymous" authentication generally used with Cams so that it can provide forms-based authentication.

Figure 21 - Adding the "cams" application to the Default Web Site

  1. Confirm the "cams" application is added to the Default Web Site. It should display as a tree node in the "Connections" pane as shown in Figure 22.

Figure 22 - The "cams" application available under the Default Web Site

Step 7 - Test the "cams" Application and Web Agent

The Cams IIS web agent should now be functional. To test, start a Cams policy server and the IIS server where you integrated the Cams web agent and configured connection values in cams-webagent.conf. If you change values in the cams-webagent.conf file, you need to restart IIS to load the changes.

  1. To test the "cams" application associated with the web agent, open a web browser window and enter a URL to the camstest.aspx page. Figure 21 shows a browser window started on the Windows 2008 server host where IIS is installed with access via the localhost host name. If the "cams" application is properly installed and ASP.NET role services are installed, you should see the camstest.aspx page like the one shown in Figure 23.

Figure 23 - Use the camstest.aspx page to test the "cams" application assicated with the web agent

  1. To test Cams login, select the "Login" button. If you've already reconfigured your Cams policy server with your production login modules, you'll need to use an account that works in your environment. NOTE: The credentials shown in Figure 23 are available with the default Cams policy server configuration using the XmlLoginModule and the cams-users.xml file-based user directory.

If the Cams IIS web agent has been correctly installed and configured, you should see Cams session information as shown in Figure 24. If you don't, please refer to the Troubleshooting section for common problems and resolutions.

Figure 24 - The camstest.aspx page after successful Cams login

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.

In the instructions that follow, it is assumed that the IIS server is started by Administrator on your Windows 2008 system. This example assumes that you are logged in as Administrator to your Windows 2008 server.

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

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.

Troubleshooting

This section contains common problems and remedies when integrating the Cams IIS web agent in IIS 7 environments. If the information in this section does not solve your integration problems, please contact Cafésoft support.

Problem: HTTP Error 405.0 when attempting Cams login

If this problem is reported, then the "Handler Mapping" for the Cams ISAPI DLL is not correctly configured. More specifically, the DLL has not been granted permission to handle "POST" requests.

Remedy: Return to Step 4 and confirm the Cams ISAPI DLL "Handler Mapping" is correctly configured.

Figure 25 - HTTP Error 405.0 reported when Cams ISAPI DLL "Handler Mapping" is incorrectly configured

Problem: HTTP Error 403.1 reported when executing cams_iis_webagent.dll

If this problem is reported, then the "ISAPI and CGI Restrictions" for the Cams ISAPI DLL is not correctly configured. More specifically, the DLL has not been granted script "Execute" permission.

Remedy: Return to Step 3 and confirm the Cams ISAPI Extension "Request Restrictions" are correctly configured.

Figure 26 - HTTP Error 403.1 reported when cams_iis_webagent.dll "Request Restrictions" are incorrectly configured

Back | Next | Contents