IIS Web Agent

Cams agents are integrated with web and application servers to protect resources that the servers provide. When a user's web browser makes a request to a web or application server, the Cams web agent asks a Cams server is access is granted or denied. The 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 web agent. The Cams IIS web agent is a Microsoft Internet Information Server version 4.0, 5.0, and 6.0 ISAPI filter and extension for Windows NT 4.0, Windows 2000, and Windows 2003 systems. The instructions that follow apply to all supported versions of Windows except where specifically noted.

NOTE: For known issues with the Cams IIS web agent, see ReleaseNotes.html found in the root directory of the Cams IIS web agent distribution.

Installation

These instructions guide you through the installation of Cams IIS web agent on a Windows NT/2000 server with IIS already installed. If IIS is not yet installed, you must first do so. You must also download the Cams IIS web agent by logging into the Cams User Portal.

The Cams IIS 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 and double click on the Setup.exe file to begin the installation. The distribution files will install by default into:

c:\cams-webagent-iis

The installer defaults to the drive Windows is installed on (typically c:). You can install to another directory, but you must preserve the Cams IIS 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 to complete the installation:

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

After installing, open the Windows explorer to the directory where your installed the Cams IIS web agent. You should see the files and subdirectories shown in Figure 1.

<!-- Cams IIS web agent documentation and license -->
README.txt
LICENSE.txt
ReleaseNotes.html
Setup.exe

<!-- Cams IIS web agent scripts and dlls files -->
cams\camsclient_mt_cams_1_0.dll
cams\cams_iis_webagent.dll
cams\denied.asp
cams\error.asp
cams\libapr.dll
cams\libcams-common.dll
cams\libcams.dll
cams\libcscore.dll
cams\libeay32.dll
cams\login.asp
cams\MSVCRTD.DLL
cams\ssleay32.dll

<!-- Cams IIS web agent configuration files -->
conf\access-control.properties
conf\cams-webagent.conf  
conf\webagent.properties

<!-- Cams IIS web agent documentation -->
docs\webagent\*

<!-- Cams IIS web agent log file directory -->
logs\

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 web agent is configured in the cams-webagent.conf file. In addition, you also need to use the Internet Services Manager to configure a filter and 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 Server Configuration section in this document for more information.

Editing cams-webagent.conf

Open the c:\cams-webagent-iis\conf\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, as shown in Table 1.

Table 1 - Import configuration values that you may need to change in cams-webagent.conf

The other properties in this file configure debug and the Cams message protocol. You should not change the message protocol values unless instructed to do so by Cafésoft support.

NOTE: The other two files in the Cams IIS web agent conf directory (access-control.properties and webagent.properties) externalize messages used by the Cams IIS web agent to report errors, warnings, etc. The contents of these files can be replaced with custom, language-specific messages. Support is not provided for the presentation of locale-specific values based upon browser international settings.

Configuring the Cams Filter

The Cams IIS web agent filter is an ISAPI extension responsible for enforcing authentication and access control decisions made by a Cams 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
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

NOTE: If you are running multiple web sites on your IIS server then you must add the Cams IIS web agent filter to each web site you want to protect. Alternatively, you can install the Cams IIS web agent filter at the IIS server-level in which case it will protect all server web sites. To do so, right click on the IIS server and select Properties. In the dialog, select the Edit button and add the Cams IIS web agent filter in the ISAPI filters tab as described above.

The order in which ISAPI DLLs execute depends on two variables: 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, denied, and error 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, 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 agent attempts to authenticate a user.

In addition, the standard Cams IIS Web Agent login, error, and access denied pages are Active Server Pages (.asp), which require use of the ASP.DLL Web Service Extension.

WARNING: If you plan to use the Cams-provided login.asp, error.asp, and denied.asp pages, you'll need to enable the associated ASP Web Service Extension. If your site already makes use of ASPs, then this extension is already enabled.

You can configure these request handlers, called Web service extensions, by manipulating the Web Service Extensions node in IIS Manager to accomplish the following: Allow and prohibit Web service extensions. Add new Web service extensions. Allow the Web service extensions that a specified application can call. 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 Administrators 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 (in some places) 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".

Securing Directories and Files

If you have not done so already, 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 NT/2000/2003 system. This example assumes that you are logged in as Administrator to your Windows NT/2000/2003 server.

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

This is done using the Windows NT/2000/2003 graphical 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: = Full Control

Scripts

The cams virtual directory includes four sample Active Server Pages (Asps) written in Microsoft Jscript:

• cams-webagent-test.asp - enables lazy and proactive authentication and access control testing, displays context sensitive information for authenticated users
• denied.asp - displays an access denied page if access to a resource request is denied
• error.asp - displays an error page if an authentication or resource request error occurs
• login.asp - displays a login page if a protected resource request is made and the user's identity is not known

cams-webagent-test.asp

You should browse to cams-webagent-test.asp to understand how to configure and use it for testing. The page is posted to the URI specified by the cams.login.uri property in cams-webagent.conf along with the following form name/value pairs:

• cams_cb_username - the username
• cams_cb_password - the user password
• cams_security_domain - the login security domain
• cams_login_config - the security domain's login-config-entry to use
• cams_original_url - The URL to redirect to after successful authentication and authorization

When you click the submit button, the Cams IIS web agent intercepts the POST to the cams.login.uri and sends the request to the Cams server. The request includes the security domain and a login-config-entry, which the Cams servers will use to attempt login. If you successfully authenticate and are authorized (depending upon how you configure the security domain), the browser is redirected to the cams_orginal_url and user specific information is displayed by cams-webagent-test.asp.

login.asp

When you request a protected resource that requires authentication and Cams doesn't know your user identity, the Cams IIS web agent displays a login page as specified in the corresponding security domain's login-config.xml file. Instead of hard coding the security domain, login configuration, and original URL, Cams dynamically provides these values to the login page as shown Example 1.

WARNING: You must correctly configure the login-parameters in the security domain's login-config.xml file or the login page will not be displayed. See the Cams Administrator's Guide - Login Configuration for more information on configuring login-parameters in login-config.xml.

<!-- Populate hidden fields from their request parameters -->
<input type="hidden" name="cams_security_domain" 
                    value="<%= Request.QueryString("cams_security_domain") %>">
<input type="hidden" name="cams_login_config"
                    value="<%= Request.QueryString("cams_login_config")    %>">
<input type="hidden" name="cams_original_url"
                    value="<%= Request.QueryString("cams_original_url")    %>">

The difference between cams-webagent-test.asp and login.asp are that you arrive at the former lazy authentication login page after requesting a resource for which your identity is unknown to the Cams server. Because of the resource request, Cams knows the security domain and login-config-entry to which the resource belongs (and, of course, the original URL).

denied.asp

If you are denied access to a resource by Cams, the page specified by the cams.denied.url property in cams-webagent.conf is displayed. Example 2 shows a script that displays dynamic messages.

<!-- Display any dynamic access denied messages -->

<%
 var message = Request.QueryString("message");
 if (message != null)
 {
%>

  <p class="error"><%= message %></p>
	
<%
 } 

 var reason = Request.QueryString("reason");
 if (reason != null)
 {
%>

  <p class="error">Reason: <%= reason %></p>
			
<%
 }

 var resourceId = Request.QueryString("resourceId");
 if (resourceId != null)
 {
%>

  <p class="error">ResourceId: <%= resourceId %></p>
			
<%
 }

 var actions = Request.QueryString("resourceActions");
 if (actions != null)
 {
%>

  <p class="error">Actions:<%= actions %></p>
	
<%
 } 
%>

cams-error.sh

If an error occurs, Cams displays the page specified by the cams.error.url property in cams-webagent.conf. Example 3 shows a script that displays dynamic messages.

<!-- Display any dynamic error messages -->

<%
 var message = null;
 message = Request.QueryString("message");
 if (message != null)
 {
%>

  <p class="error"><%= message %></p>

<%
 } 
%>

NOTE: In order to ensure that the browser does not cache these pages, it is important that you use the following HTML Meta tags in the HEAD section of each page:

<meta http-equiv="Pragma"        content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">  		
<meta http-equiv="Expires"       content="-1">

Optimizations

The Cams IIS web agent installs with default configuration properties. However, you may find it beneficial to configure your installation to more adequately meet the requirements of your environment. See the following documentation regarding available Cams web agent optimizations: Cams Web Agent Optimizations.

Cams Server Configuration

Before you start the IIS server with a Cams IIS web agent, you'll need to ensure that the Cams server knows about it. See the following documentation, which explains Cams server configuration requirements for each web/application server and Cams agent: Web Agent-specific Cams Server Configuration.

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 server, test the configuration using:

http://[hostname:port]/cams/cams-webagent-test.asp

Login to an account in the security domain that you've established. See the test page for more configuration and testing information

Back | Next | Contents

© Copyright 1996-2003 Cafésoft LLC. All rights reserved.