|Back | Next | Contents||Cams IIS HttpModule Web Agent Guide|
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 HttpModule Windows web agent, which is an IIS HttpModule for:
NOTE: If you are using a 64-bit Windows operating system, we recommed you use the Cams IIS HttpModule Windws x86/64-bit web agent.
Support for the IIS 6 ISAPI API is provided by the Cams IIS ISAPI web agent. If you need support for another operating system, hardware architecture, or web server API, please contact Cafésoft support.
NOTE: For known issues with the Cams IIS HttpModule web agent, see ReleaseNotes.html found in the root directory of each web agent distribution.
These instructions guide you through the installation of Cams IIS HttpModule Windows web agent on supported operating system configurations with IIS already installed. If IIS is not yet installed, you must first do so. You must also download the Cams IIS HttpModule x86/32-bit web agent.
The 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 (e.g. C:\tmp) and double click on the Setup.exe file to begin the installation. The distribution files will install by default into:
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-httpmodule. You must also preserve the Cams IIS HttpModule 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:
After installing the web agent, open the Windows explorer to the installation directory. You should see the files and directories shown in Figure 1.
<!-- Cams IIS HttpModule web agent documentation and license --> README.txt LICENSE ReleaseNotes.html unins000.dat unins000.exe <!-- Cams IIS HttpModule web agent scripts and dlls files --> cams\cams_iis_webagent_http_module.dll cams\camsclient_mt_cams_3_0.dll cams\camstest.aspx cams\cams_iis_webagent.dll cams\libapr-1.dll cams\libapriconv-1.dll cams\libaprutil-1.dll cams\libcams.dll cams\libcams-common.dll cams\libcsconv_apr_1_0.dll cams\libcscore.dll cams\libeay32.dll cams\login.aspx cams\msvcr100.dll cams\prce.dll cams\slo.aspx cams\slo.gif cams\ssleay32.dll <!-- Internationalization/Character conversion libraries --> cams\iconv\*.so <!-- Cams IIS HttpModule web agent configuration files --> conf\access-control.properties conf\cams-webagent.conf conf\webagent.properties <!-- Cams IIS HttpModule web agent log file directory --> logs\
Figure 1 - Directory listing of the Cams IIS HttpModule 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.
The Cams IIS HttpModule web agent is configured in the cams-webagent.conf file. In addition, you also need to use the Internet Services Manager to register a native module and create 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.
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.
Integrating the Cams IIS HttpModule web agent on IIS 7.* involves the following major steps:
Here you register and optionally enable the IIS web server with the "global" level Cams HttpModule web agent DLL. The global web agent HttpModule DLL is a "Native Module", which is used to extend server functionality and must be registered at the "Connection" level only for global IIS server availability.
NOTE: This web agent DLL works in conjunction with a "request" level web agent HttpModule DLL described in the next step.
Here you register and enable the IIS web server with the "request" level Cams HttpModule web agent DLL. The request-level web agent HttpModule DLL is also a "Native Module" and must also be registered at the "Connection" level, but may be enabled or disabled at the "Connection", "Web Site" and/or "Application" levels.
NOTE: You must also configure the "global" web agent HttpModule DLL for the request-level Cams HttpModule web agent DDL to work.
The cams application provides the login page, a Cams test page, and various "virtual URLs" used to handle login, logout, and other web agent actions. The cams application is added to the IIS Default Web Site, but may be used by any/all web sites configured within IIS.
You use the camstest.aspx page within the cams application to confirm that the Cams IIS HttpModule web agent is configured correctly to connect to a Cams policy server, authenticate users and access Cams session cookie and HTTP request header data.
By default, the Cams IIS HttpModule web agent will be enabled for all web sites and applications under a given connection. If you'd like to include or exclude specific web sites and/or applications for protection by the Cams web agent, you can follow the guidelines in step 5.
This section provides step-by-step instructions for configuring the Cams IIS HttpModule 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.
Figure 2 - IIS Manager with the "Home" Connection selected
Figure 3 - Configured Modules at the Connections Level before teh Cams IIS HttpModule is registered
Figure 4 - Registered Native Modules before the Cams IIS Global HttpModule is registered
Figure 5 - Registering the Cams IIS Global HttpModule native module
Figure 6 - Registered Native Modules after the Cams IIS Global HttpModule is registered
Figure 7 - Configured Modules at the Connections Level after the Cams IIS Global HttpModule is registered
Figure 8- IIS Manager with the "Home" Connection selected
Figure 9- Configured Modules at the Connections Level before the Cams IIS Request HttpModule is registered
Figure 10- Registered Native Modules before the Cams IIS Request HttpModule is registered
Figure 11- Registering the Cams IIS Request HttpModule native module
Figure 12- Registered Native Modules after the Cams IIS Global HttpModule is registered
Figure 13- Configured Modules at the Connections Level after the Cams IIS Global HttpModule is registered
Figure 8 - The Default Web Site before the "cams" application is added
Figure 9 - The Default Web Site properties "Add Applcation..." menu item
Figure 10 - The "Add Application" dialog box completed to add the "cams" Application
Figure 11 - The Default Web Site after the "cams" application is added
Figure 12 - Confirming the global and request level modules are configured for the "cams" application
The Cams IIS HttpModule 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 12 - Use the camstest.aspx page to test the "cams" application assicated with the web agent
If the Cams IIS HttpModule web agent has been correctly installed and configured, you should see Cams session information as shown in Figure 13. If you don't, please refer to the Troubleshooting section for common problems and resolutions.
Figure 13 - The camstest.aspx page after successful Cams login
After initial installation of the Cams IIS HttpModule web agent "global" and "request" level modules, all web sites and applications below each web site are protected by the web agent. If you'd like the web agent to protect only some web sites and/or some applications within web sites, you can fine tune you configuration by enabling or disabling the "request" level module at the connection, web site, and/or application levels. IIS provides you with the ability to:
For example, suppose we have the following resources hosted under IIS:
Connection: WIN2008 Web Site: www.domain1.com Application: A Application: B Web Site: www.domain2.com Application: C Application: D
You may implement this scenario by:
or, you could implement the same scenario by:
The configuration using the least number of settings to implement this scenario are:
Obviously, many more scenarios are possible, but our recommendation is to minimize the number of settings throughout the Connection, Web Site, and Application hierarchy by choosing settings at given level that apply to the most number of immediate child nodes. So, if you are hosting ten web sites under an IIS connection and seven of them are to be protected by the Cams web agent, it would be simplest to enable the request-level module at the Connection level and inherit those settings at all web sites except the three that don't need the Cams web agent.
To see if the Cams IIS HttpModule web agent is enabled at one of these levels, simply select the Connection, Web Site, or Application in the IIS Manager "Connections" pane, then double click on the "Modules" icon in the Features View. For example, Figure 14 shows the modules for the "Default Web Site". As you can see the "request" level web agent module is present (enabled). If the applications below the web site inherit module settings, then all will be protected by the web agent.
Figure 14 - The web agent request and global level modules enabled for a web site
To disable the Cams IIS HttpModule web agent for the Default Web Site, select the "cams-iis-request-httpmodule", then click on the "Remove" menu item in the "Actions" pane. A dialog box like the one shown in Figure 15 will be displayed. Select the "Yes" button to remove the request-level web agent module for the web site.
Figure 15 - Confirming removal of the web agent request level module for a web site
After the request-level module is removed for the Default Web Site, the list of module contains only the "global" level module and not the "request" level module as shown in Figure 16.
Figure 16 - The web agent request level module disabled for a web site
If you wanted to enable the web agent for the web site, you could:
Figure 16 - The "Configure Native Modules" dialog box showing the web agent request level module disabled for a web site
Figure 17 - The "Configure Native Modules" dialog box: enabling the web agent request level module for a web site
Similar control exists for for enabling or disabling modules at the Connection, Web Site, and Application levels. NOTE: modules may not be enabled or disable for a "Virtual Directory" within a web site. Virtual directories alway inherit the settings for their immediate parent container: a web site or an application.
One of the easiest ways to see if the Cams IIS HttpModule web agent is enabled or disabled for a web site or an application is to use the "camstest.aspx" file. This file will display Cams session cookies and HTTP request headers if you are logged into your web site and the agent is enabled.
To use this technique, simply:
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 HttpModule 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.
NKK: TBD based on actual problems encountered. Possible conditions to simulate: