|Back | Next | Contents||Cams Web Agent Guide|
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.
Integrating the Cams IIS web agent on IIS 7 involves the following major steps:
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.
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.
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.
You'll need to allow .dll files to execute in the IIS environment. The ISAPI-dll handler is configured to enable Execute permission.
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.
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.
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.
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.
To add the IIS service roles (features) needed by the Cams web agent:
You should see the controls shown in Figure 1.
Figure 1 - Adding features (role services) needed by the Cams IIS web agent
Figure 2 - After adding role services needed by the Cams IIS web agent
Figure 3 - After confirming role services needed by the Cams IIS web agent
Figure 4 - Installation results after role services needed by the Cams IIIS web agent have been added
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.
Figure 6 - The IIS Server Features available for IIS Home
Figure 7 - The available ISAPI Filters before the Cams IIS web agent ISAPI filter is added
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.
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.
Figure 10 - Adding the Cams IIS web agent DLL as an ISAPI Extension
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.
This step is required to allow .dll files to execute in the IIS environment. The "ISAPI-dll" handler is configured to enable "Execute" permission.
Figure 12 - Editing the script map for ISAPI-dlls
Figure 13 - Setting the "Mapping" for ISAPI DLLs
Figure 14 - Enabling use of all verbs (GET, POST, HEAD, etc) for ISAPI DLLs
Figure 15 - Setting "Execute" access for ISAPI DLLs
Figure 16 - The "Edit Script Map" confirmation dialog box
Figure 17 - The "cams" application with "Read", "Script", and "Excecute" permissions enabled
Figure 18 - Handler Mappings with the ISAPI-dll "Enabled" for "File or Folder"
Changes to "Handler Mappings" are now complete.
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.
Figure 19 - Selecting the DefaultAppPool to edit the associated "Advanced Settings..."
Figure 20 - Selecting the defaultHandler Mappings with the ISAPI-dll "Enabled" for "File or Folder"
The "cams" application is responsible for hosting the login page, a test page, and for handling Cams login requests.
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
Figure 22 - The "cams" application available under the Default Web Site
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.
Figure 23 - Use the camstest.aspx page to test the "cams" application assicated with the web agent
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
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:
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.
This is done using the Windows user interface.
From the same Security tab used in Step 1:
Debugging information is available in the following web server-specific logs:
During Cams web agent integration, it is helpful to set the following values in cams-webagent.conf:
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.
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.
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
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