Back | Next | Contents Cams IIS HttpModule Web Agent Guide

IIS HttpModule 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 HttpModule Windows web agent, which is an IIS HttpModule for:

  • IIS 7.0, 7.5, 8.0 or 8.5
  • Windows 2012 Server R2 for AMD/Intel x86 64-bit
  • Windows 2012 Server for AMD/Intel 64-bit
  • Windows 2008 Server for AMD/Intel x86 32-bit and 64-bit
  • Windows 2008 Server R2 for AMD/Intel x86 64-bit

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.

Installation

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:

c:\cams-webagent-iis-httpmodule

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:

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

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.

Web Agent Configuration

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.

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.

Integration Overview

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

1. Configure the Web Agent Native Global-Level Module

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.

2. Configure the Web Agent Native Request-Level Module

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.

3. Configure the "cams" Application

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.

4. Test the "cams" Application and Web Agent

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.

5. (Optional) Enable and/or Disable Protection for Web Sites and/or Applications

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.

Step-by-Step Integration Instructions

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.

Step 1 - Configure the Web Agent Native Global-Level Module

  1. Start the IIS Manager.
  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 2.
  3. Figure 2 - IIS Manager with the "Home" Connection selected

  4. Double click on the "Modules" icon. You should see a list of modules like those shown in Figure 3.
  5. Figure 3 - Configured Modules at the Connections Level before teh Cams IIS HttpModule is registered

  6. In the "Actions" pane, select "Configure Native Modules...". A dialog box like the one shown in Figure 4 should display.
  7. Figure 4 - Registered Native Modules before the Cams IIS Global HttpModule is registered

  8. Select the "Register..." button to display the "Register Native Module" dialog box. Enter "cams-iis-httpmodule-webagent" in the "Name" field. Select the "..." button and browse to the "cams_iis_webagent_http_module.dll" file and select it to populate the "Path" field. The completed dialog box should look like Figure 5.
  9. Figure 5 - Registering the Cams IIS Global HttpModule native module

  10. Select the "OK" button in the "Register Native Module" dialog box to save the native module configuration. The "Configure Native Modules" dialog box will contain the "cams-iis-global-httpmodule" module checked (enabled) as shown in Figure 6.

    NOTE:
    The global-level module cannot be disabled due to the Microsoft API it uses. Even if the associated check box is optionally "unchecked", the global-level web agent module will still be "enabled" and execute for every request in all web sites and all applications. Despite this limitation, the global-level web agent module performs negligible work unless triggered by a downstream "request" level web agent module. We recommend leaving the checkbox "checked" so the module will display in the native module list as shown in Figure 7.
  11. Figure 6 - Registered Native Modules after the Cams IIS Global HttpModule is registered

  12. Select the "OK" button in the "Configure Native Modules" dialog box to save the native modules configuration. The "Modules" list will contain the "cams-iis-httpmodule-webagent" native module as shown in Figure 7. The Cams IIS HttpModule web agent native module is now registered and enabled.
  13. Figure 7 - Configured Modules at the Connections Level after the Cams IIS Global HttpModule is registered

Step 2 - Configure the Web Agent Native Request-Level Module

  1. Start the IIS Manager.
  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 8.
  3. Figure 8- IIS Manager with the "Home" Connection selected

  4. Double click on the "Modules" icon. You should see a list of modules like those shown in Figure 9. NOTE: the cams-iis-global-httpmodule is already registered.
  5. Figure 9- Configured Modules at the Connections Level before the Cams IIS Request HttpModule is registered

  6. In the "Actions" pane, select "Configure Native Modules...". A dialog box like the one shown in Figure 10 should display.
  7. Figure 10- Registered Native Modules before the Cams IIS Request HttpModule is registered

  8. Select the "Register..." button to display the "Register Native Module" dialog box. Enter "cams-iis-request-httpmodule" in the "Name" field. Select the "..." button and browse to the "cams_iis_request_http_module.dll" file and select it to populate the "Path" field. The completed dialog box should look like Figure 11.
  9. Figure 11- Registering the Cams IIS Request HttpModule native module

  10. Select the "OK" button in the "Register Native Module" dialog box to save the native module configuration. The "Configure Native Modules" dialog box will contain the request module checked (enabled) as shown in Figure 12. Leave this checked to enable the request-level module for all inheriting connections and applications.

    NOTE:
    The request-level module can be enabled or disabled at this or any level. However, care should be exercised to not leave connections and applications that required Cams security unprotected.
  11. Figure 12- Registered Native Modules after the Cams IIS Global HttpModule is registered

  12. Select the "OK" button in the "Configure Native Modules" dialog box to save the native modules configuration. The "Modules" list will contain the "cams-iis-request-httpmodule" native module as shown in Figure 13. The Cams IIS HttpModule web agent native modules are now configured and enabled.
  13. Figure 13- Configured Modules at the Connections Level after the Cams IIS Global HttpModule is registered

Step 3- Configure the "cams" Application

  1. In the "Connections" pane, expand the "Sites" node, expand the web site node (e.g. Default Web Site) in which to add the "cams" application as shown in Figure 8. NOTE: if your IIS web server hosts web sites with differnt DNS domains (e.g. domain1.com and domain2.com) and you'd like to use Cams with those web sites, then you may want to add the "cams" application each web site so you can use use camstest.aspx and host different login.aspx pages for each web site.
  2. Figure 8 - The Default Web Site before the "cams" application is added

  3. Right click on the web site node in which you'd like to add the "cams" application (e.g. Default Web Site) and select the "Add Application..." menu item as shown in Figure 9.
  4. Figure 9 - The Default Web Site properties "Add Applcation..." menu item

  5. In the "Add Application" dialog box, enter "cams" for the Alias. In the Physical Path field, browse to and select the "C:\cams-webagent-iis-httpmodule\cams" directory (or whatever the installation path is to your "cams" directory) as shown in Figure 10. Select the "OK" button to save the application settings.
  6. Figure 10 - The "Add Application" dialog box completed to add the "cams" Application

  7. Confirm that your web site contains a "cams" application as shown in Figure 11. At this point, the Cams IIS HttpModule web agent is ready for installation testing.
  8. Figure 11 - The Default Web Site after the "cams" application is added

  9. Confirm that the "cams" application has the global and request level modules configured by double clicking on the "Modules" icon while the "cams" application is selected. You should see both modules registered and enabled as shown in Figure 12. At this point, the Cams IIS HttpModule web agent is ready for installation testing.

Figure 12 - Confirming the global and request level modules are configured for the "cams" application

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

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.

  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 12 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 13.

Figure 12 - 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 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

Step 5 - (Optional) Enable and/or Disable Protection for Web Sites and/or Applications

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:

  1. Inherit module settings from a higher level: Web Sites may inherit from the parent Connection, and Applications may inherit from the parent Web Site or from the parent Connection.
  2. Override inherited module settings: Web Sites may override settings inherited from the parent Connection, and Applications may override the settings from the parent Web Site or from the parent Connection.

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

Scenario 1: Protect all applications only under Web Site: www.domain1.com

You may implement this scenario by:

  • enabling the web agent request-level module at the Connection level
  • inheriting module settings for Web Site: www.domain1.com
  • inheriting Web Site module settings for Application A and Application B
  • disabling the web agent request-level module for Web Site: www.domain2.com
  • inheriting Web Site module settings for Application C and Application D

or, you could implement the same scenario by:

  • disabling the web agent request-level module at the Connection level
  • ovrriding the module settings for Web Site: www.domain1.com (enabling the web agent request-level module)
  • inheriting Web Site module settings for Application A and Application B
  • inheriting module settings for Web Site: www.domain2.com
  • inheriting Web Site module settings for Application C and Application D

Scenario 2: Protect only Application A and Application C

The configuration using the least number of settings to implement this scenario are:

  • disabling the web agent request-level module at the Connection level
  • inheriting module settings for Web Site: www.domain1.com
  • ovrriding the module settings for Application A: (enabling the web agent request-level module)
  • inheriting Web Site module settings for Application B
  • inheriting module settings for Web Site: www.domain2.com
  • ovrriding the module settings for Application C: (enabling the web agent request-level module)
  • inheriting Web Site module settings for Application D

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.

Enabling or Disabling the web agent at the Connection, Web Site or Application Levels

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:

  1. Select "Revert to Parent" in the "Actions" Pane, which would revert to using the enabled "request" level web agent module. NOTE: if you've customized other module settings for the web site, then "Revert to Parent" would also revert those settings. There's no way to "undo" the "Revert to Parent" action, so be careful when using this option.
  2. Select "Configure Native Modules..." in the "Actions Pane", which displays a dialog box like the one shown in Figure 17. Select the check box to the left of the "cams-iis-request-httpmodule" as shown in Figure 18, then select the "OK" button to apply the change. The list of web site modules will not include the "request" level module again.

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.

Testing whether the web agent is enabled or disabled for a Web Site or 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:

  1. Copy the file from the "cams" application root directory into a web site directory and/or the application directory you'd like to test.
  2. Use a web browser to login to Cams using the "camstest.aspx" page in the "cams" application. (e.g. http://localhost/cams/camstest.aspx). On successful login, you should see the Cams session cookie value and various Cams HTTP request headers.
  3. Navigate to the web site "camstest.aspx" page. (e.g. http://localhost/camstest.aspx). If the session cookie and request header values are displayed, then the web site is protected by the web agent. If they are not displayed, the web agent is not enabled at the web site level.
  4. Navigate to the application "camstest.aspx" page. (e.g. http://localhost/app1/camstest.aspx). If the session cookie and request header values are displayed, then the application is protected by the web agent. If they are not displayed, the web agent is not enabled at the application level.

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 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.

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.

NKK: TBD based on actual problems encountered. Possible conditions to simulate:

  • Web agent HttpModule not registered
  • Cams application not installed in web site
  • Executing service user incompatible with file permissions

Back | Next | Contents