Installing CUWebAuth

This page describes the installation process for IIS.

Installing with IIS (Windows)

Hardware/OS Requirements

CUWebAuth runs as a DLL “ISAPI Filter” on Windows Internet Information Server 4.0 and up, on Windows NT 4.0 and up (including Windows 2000, Windows 2003 ) . In addition to the CUWebAuth DLL itself, there are additional DLLs, which are installed in order to provide the proper Kerberos functionality. It is not necessary to install any Bear Access or Kerberos/SideCar software on the machine, though each of these software distributions include some of the same Kerberos DLLs as CUWebAuth. There is no particular hardware requirement for CUWebAuth. If your hardware configuration can comfortably run IIS, adding CUWebAuth should be fine as well.

Note for users of IIS 6.0 on Windows 2003:

You can run the CUWebAuth.DLL (Non POST data aware) in normal m ode. But for the logging to work, you have to create a CUWebAuth.log file and give users write permissions.

Installation

To install CUWebAuth, you must download the zip from http://identity.cit.cornell.edu/authn/cwa_dl.html. There are two versions of CUWebAuth, the POST data aware version CUWebAuth142post.zip , and the standard (non-POST data aware) version CUWebAuth142.zip . Install the POST data aware version if your website supports form data submissions and you need form data preserved across login attempts. Without the post version if a user is prompted for a login during form submission the form data will be lost. We do not recommend installing the POST version unless it is clearly necessary, refer to the best practices section if you decide to use POST data aware version.

Reason for two versions of CUWebAuth

The following are the reasons for having 2 versions of CUWebAuth:

a) IIS 6.0 in normal mode does not support

SF_NOTIFY_READ_RAW_DATA notification which is used

by POST data aware CUWebAuth.

b) POST data aware CUWebAuth has a significant performance impact on IIS when there is a large POST data transaction involved.

Web servers, which do not support POST data, should not be impacted with this. So two versions are released. See Best Practices section for more information on how to control the performance impact on IIS for the POST data aware CUWebAuth.

To install CUWebAuth unzip the zip file to a location of your choice. We recommend C:\CUWebAuth. You must then copy the krb.con file to your windows directory. If you already have a krb.con from a previous installation this step is not necessary. The included readme file has an installation checklist

If you are upgrading we recommend stopping IIS before replacing an existing version.

Configuring IIS for use with CUWebAuth

Configuring IIS simply involves adding the CUWebAuth DLL to the list of filters in use in the Internet Services Manager on your system. To begin, right-click on the “My Computer” icon on your desktop and choose “Manage”. You should see a window that looks roughly like this:

Manage option in context menu for My Computer

In the left pane of this window, right-click on the “Internet Information Services” label and choose “Properties”. You will see the following screen:

IIS Properties from context menu of Internet Information Services

At this point, click the “Edit” button that is inside the “Master Properties” area of the dialog (not the MIME Map area). You will be presented with the following dialog:

Editing Master Properties for WWW Service

If the ISAPI Filters tab is not selected, please select it now.

What you will see is a list of all the ISAPI filters that are loaded for your installation of IIS (which may vary from the example shown based on what else you have installed in your environment). The green “up arrow” next to each filter, means that the filter is currently running. The value in the “Priority” column gives the precedence each filter is given when handling requests (Those of higher priority see the request first).

ISAPI Filters tab in WWW Service Master Properties

In order to continue the installation process, you need to add the CUWebAuth filter into this filter list. Do so by clicking the “ Add” button. You will be presented with the following dialog:

Add Filter dialog box

Initially, this dialog will be blank. You need to specify the name of the filter and the path to the filter itself. The default install location of the CUWebAuth.DLL file is in a directory named “CUWebAuth” in the Windows directory (unless you changed it in the initial setup screens when running the installer).

You may use the “Browse” button to graphically navigate to the location of that file.

While you may put any name you’d like in the “Filter Name:” field, using “CUWebAuth” should a void any confusion down the road. When the information is entered and correct, click on the “OK” button to proceed.

After you’ve specified the location of the CUWebAuth filter, you will be returned to the ISAPI Filter tab in the Master Properties dialog. You will then see that the CUWebAuth fiter is in the list, but not loaded:

CUWebAuth filter added, but not yet loaded

At this point, you need to restart IIS in order to have CUWebAuth load. Click “OK” in the dialog and return to the IIS Properties dialog. Click “OK” in that dialog as well and you will be returned to the Computer Management screen.

Restarting IIS from Computer Management window

In order to restart IIS, right click the Internet Information Services label and choose the “Restart IIS” menu option. You will be presented with a dialog that asks you to confirm your choice. Click “OK” to continue.

After IIS restarts, you can verify that CUWebAuth loaded by returning to the ISAPI Filters tab (review the instructions for navigating to that dialog earlier in this chapter). If CUWebAuth shows in the ISAPI filter list with a green arrow and “Medium” priority, the filter is loaded:

Verifying that CUWebAuth successfully loaded

By default, the CUWebAuth filter runs at “Medium” priority. In many server environments it will be necessary to change this to “high”. This is especially true of servers running JRun based applications such as JSP, ColdFusion, and servlets. The change of priority can be accomplished via the CUWApriorityLevel directive in your CUWebAuth.conf file .

Once loaded, you are ready to configure CUWebAuth.