Pubcookie Home > Documentation 
 
Pubcookie Homepage Pubcookie 3.2
ISAPI Filter Installation Guide
Component:  Pubcookie ISAPI Filter
Audience:  All
Modified:  June 17, 2005

Included on this page:

Overview

This guide helps Microsoft Internet Information Server administrators to install, configure and use the Pubcookie 3.2 ISAPI filter, herein referred to as, simply, the filter.

The filter controls user authentication. When a resource is protected with a Pubcookie authentication type, access to the resource is controlled by the filter and users must be able to get through the authentication process before IIS can serve the requested resource. The filter sets a HTTP_PUBCOOKIE_USER server variable containing the user's id when authentication is successful.

The filter does not provide authorization; it's up to the resource/application to decide what the authenticated user is privileged to do.

What's New

Significant improvements since version 3.1.1:

  • PubcookieFilter DLL now acts as an ISAPI extension as well as an ISAPI filter. As before, the filter manages access to resources and initiates authentication. The extension has been added to consume replies from the login server. Together, they implement the POST-based login method introduced in the Pubcookie 3.2.0 Apache module. This change effectively replaces the classic enterprise-cookie-based method used in the past. As a result, Enterprise_Domain has been removed from the installer and MMC snap-in, and the relay cgi has been removed altogether.

  • Updated Windows Installer package (Pubcookie.msi). Site Information screen now provides 3 keyclient options: obtain new key, retrieve old key, or don't run keyclient at all. Also, the installer now continues after keyclient errors rather than rolling back; this allows you to troubleshoot and then re-run the keyclient manually to obtain granting certificate and encryption key.

  • Enhanced Keyclient.exe. When run manually, it offers a certificate picker to choose among multiple valid certificates.

  • Fixed problems reading registry settings. The filter is more consistent about reading and applying default configuration, as well as configuration defined through alternate WebVarLocations. The related bugs in version 3.1.1 have been fixed.

  • Updated Cache-control headers. The Pubcookie filter matches the Apache module's headers for redirections to the login server.

  • Favicon location exempted. Fixes problems with some browsers, especially Firefox, when the favicon is protected.

  • Updated OpenSSL 0.9.7.f libraries.

  • Other bug fixes and improved memory management.

Prerequisites

The filter relies on additional infrastructure at your site. Here are some general prerequisites that, if fulfilled, will lead to a smooth, successful installation.

  • Determine the location of your site's Pubcookie login server. The installer needs this URL during installation. You may also want to find out its version, so that you know what features it supports.

  • Determine the location of your site's Pubcookie keyserver. The installer needs this URL to download your site's Pubcookie "granting" certificate and to request a symmetric encryption key that your server will share with your login server. Depending on the keyserver version and site policy, you may also need to ask your administrator to "permit" your server to request keys.

  • Determine how trust is handled by your site's Pubcookie keyserver. You'll need to know which Certificate Authorities the keyserver trusts to verify certificates. Similarly, you'll need to know which Certificate Authority can verify the keyserver's certificate. Ask your administrator for guidelines; it'll save you time and effort.

Note: Review the sections on multiple web site configuration or clustered host configuration now if either of those scenarios apply. The information will help you think about and tailor the installation as needed.

System Requirements

The Pubcookie ISAPI filter has the following system requirements:

  • Microsoft Windows 2000 or later

  • Microsoft Internet Information Server (IIS) 4.0 or later

  • Accurate system time

  • Domain name registered in DNS (e.g. appserver.example.edu).

  • An SSL enabled web site. All intended users should be able to reach your website via HTTPS at your registered DNS name without errors.

  • The System32\inetsrv folder should be world writable or writable by the administrator account running the installer.

Installing Pubcookie

This section describes how to install Pubcookie using the provided Windows Installer package (Pubcookie.msi). We'll cover a fairly typical installation and note significant exceptions and more advanced uses when possible.

  1. Log in as Administrator or as an account with administrator privileges. The installer needs to be able to create folders and files in System32\inetsrv, to stop and start system services, to modify the Windows registry, and to read keys in the Windows certificate store.

    Note: The installer can be run from the command prompt, or from within a batch file, with pre-defined site information. See the msiexec options section for details.

  2. Run the Pubcookie.msi installer. Click Next on the initial Welcome screen.

    Note: If the installer says, mysteriously, "interrupted before Pubcookie3 could be completely installed", click Finish and run it again.

  3. Pubcookie is licensed under the Apache License, Version 2.0. If you accept the terms of the license, select the appropriate radio button and click Next.

  4. The Site Information screen lets you enter your server name, login server and keyserver locations, authentication flavors, and lets you select your desired keyclient behavior. Enter your Site Information and click Next.

    Note: Your server name should match the Common Name of your site's SSL certificate.

  5. The Custom Setup screen lets you choose what to install and where to install it. By default, the filter and sample web application are selected, with fairly standard installation locations. Adjust as needed and click Next.

  6. The Ready screen indicates the installer is ready. Read through the steps below to learn what it's going to do. It will display a Status bar, and provide a Cancel button which is fairly good at rolling things back out, but this is the stage where installation really begins. When you're ready to proceed, click the Install button.

  7. Installation begins by adding Pubcookie to the Root Filter list in the IIS Metabase. If you instead want to add Pubcookie to specific web sites, use the Internet Information Services (IIS) Manager to do so after installation. (Hereafter referred to as the IIS Manager, you can find it at Start > Programs > Administrative Tools.)

    Installation also adds your Site Information to the Windows registry as your initial Pubcookie configuration settings and installs a MMC snap-in that adds Pubcookie configuration tabs to Properties dialogs within the IIS Manager.

  8. Next, your IIS Service will be stopped.

  9. The installer will now run the keyclient according to the behavior you selected on the Site Information screen. The default behavior is to request your site's granting certificate and generate a new key, both of which are saved to a new System32\inetsrv\Pubcookie\keys\ folder. Click OK on the corresponding pop-up messages from the keyclient.

    Note: The keyclient must find a certicate and private key in your Personal certificate store that matches the server name entered in the Site Information screen. It uses this key pair to negotiate a secure SSL/TLS authenticated connection to your key server. This connection depends not only on your certificate and the Certificate Authority that issued your certificate, but also on the Certificate Authority that issued your keyserver's certificate.

    Note: If the keyclient fails, you'll need to re-run it after the installer finishes.

  10. Next, your IIS Service will be started.

    [fixme: do we mention here that the filter is initialized and a new session key pair is generated?]

  11. When the installer has completed, click Finish.

Web Service Extension Configuration (IIS 6.0)

Installation on IIS 6.0 requires additional configuration to add and allow a new Web Service Extension for Pubcookie.

  1. Using the IIS Manager, select Web Service Extensions and click "Add a new Web service extension..."

  2. On the New Web Service Extension dialog, enter .pubcookie3 for the Extension name, click Add..., click Browse and browse to and then Open the System32\inetsrv\pubcookie\PubCookieFilter.dll, click OK, then check the box to Set extension status to Allowed, and click OK.

  3. The resulting Web Service Extension for Pubcookie will be added to the list. The Status should be Allowed.

Reviewing Pubcookie Installation

A successful installation of Pubcookie includes the following items:

  • ISAPI filter. See IIS Master Properties > Edit > ISAPI Filters. Status should be up/green; priority should be Low.

  • ISAPI extension. See IIS Master Properties > Edit > Home Directory > Configuration... > Application Mappings. A .pubcookie3 Extension should be present with an Executable Path pointing to the PubcookieFilter DLL.

  • Pubcookie MMC snap-in configuration tabs. See Pubcookie Server Variables and/or Pubcookie Directives tabs added to Properties dialogs opened in the IIS Manager.

  • Pubcookie folder. This folder contains the keyclient, DLL files, license, and keys folder. See System32\inetsrv\Pubcookie.

  • Pubcookie keys folder. This folder contains your host key(s), granting certificate, and a session key pair if you've created one on disk. See System32\inetsrv\Pubcookie\keys.

  • PubcookieFilter Windows registry key. The primary registry key for Pubcookie is System\CurrentControlSet\Services\PubcookieFilter.

  • Event log sources. The installer registers several event log sources for Pubcookie. See the main Pubcookie key, plus one for each IIS Instance ID, under System\CurrentControlSet\Services\EventLog\Application.

  • Sample Web application. A sample web application demonstrates how authentication information is provided by the filter. See wwwroot\webapp.

  • Windows Installer package (Pubcookie.msi). [fixme: why would one want to keep the installer around? perhaps for re-installs, uninstalls?]

Pubcookie Configuration Overview

Pubcookie dervies its behavior from configuration settings in the Windows registry. Use the IIS Manager to view and manage these settings. They fall into two categories, Pubcookie Server Values and Pubcookie Directives.

Pubcookie Server Values apply configuration behaviors to Pubcookie itself. They can be found under your master or web site propeties. Click the Pubcookie Server Values tab.

Pubcookie Directives apply configuration behaviors to specific resources: web sites, folders, even individual files. They can be found under the resource properties. Click the Pubcookie Directives tab.

How to Configure Authentication

Use the IIS Manager to apply Pubcookie authentication to a resource. For example, if you installed the sample web application, follow these steps to view and modify how its configured for authentication:

  1. Browse to the Webapp in the IIS Manager and open its Properties.

  2. Select the Pubcookie Directives tab and choose the AuthType directive from the drop-down menu.

  3. To enable authentication, select the appropriate value. To disable authentication, select None.

    Note: AuthType values are determined by the Authentication Flavor Names entered during installation. They correspond with the types (or, technically, flavors) of authentication provided by your Pubcookie login server. Typically, just one flavor is supported, but some sites have two or more. The menu values are stored as Pubcookie Server Values.

  4. When you click Apply (or click OK, after making more than one change within the Properties dialog), your configuration choices will be written to the appropriate registry key.

  5. The filter reads the AuthType value on every request, so configuration changes should be reflected immediately.

Running Keyclient.exe

The Pubcookie keyclient for Windows (System32\inetsrv\pubcookie\keyclient.exe) is used to securely obtain encryption keys for your server name(s). It uses the SSPI/SChannel libraries to negotiate a SSL/TLS authenticated connection to the keyserver, using credentials and trusted certificate authority (CA) information from the Windows certificate store. Most likely it will use the same Server (SSL) Certificate used by IIS for secure HTTPS communications.

The keyclient supports the following command-line options:

  • -H <hostname> (Client hostname. Used to search certificate store for a certificate with a matching SubjectAltName or Subject/CN.)

  • -K <location> (Key Server URL; defaults to Keymgt_URI registry setting.)

  • -d (Download current key; without this option it will obtain a new key.)

  • -G (Obtain your site's Pubcookie granting certificate.)

  • -I (Run in simplified installer mode. )

[fixme: other options?]

For example, to request a key for appserver.exampled.edu from login.example.edu, you would use the -H and -K options.

> cd C:\WINNT\system32\inetsrv\pubcookie
> pubcookie.exe -H appserver.example.edu -K https://login.example.edu:2222 

Note: The keyclient skips over expired certificates in its search for one that matches the specified (-H) hostname.

Note: When run from the command prompt, the keyclient will allow you to pick which certificate to use if it finds more than one that matches.

Clustered Host Configuration

If the same server name is hosted on several machines, you have a clustered host configuration and will need to synchronize your installation and configuration among the cluster members. In particular, you need to make sure each member has a copy of the same encryption key and is using the same Pubcookie session key pair.

  1. To synchronize the host key, when you run the installer on the first host, set the installer's keyclient behavior to obtain a new key. On subsequent hosts, set it to retrieve the old key. Another method is to obtain a new key on the very last host and then copy it to the previous hosts.

  2. To ensure each cluster member has the same session key pair, put the same key pair on each host, on disk, in the right location, and the filter will read it upon startup. The file names are System32\inetsrv\Pubcookie\keys\pubcookie_session.cert and System32\inetsrv\Pubcookie\keys\pubcookie_session.key, respectively.

    Note: any appropriately named key pair in PEM format will suffice for the session key pair. The difficulty on Windows is generating a key pair. If you can find a system that has OpenSSL, you can generate a new key pair with:

    $ openssl req -new -x509 -out pubcookie_session.cert \
    -newkey rsa:1024 -nodes -keyout pubcookie_session.key

    [fixme: there must be an easier way using Windows crypto API commands.]

  3. As a result of this effort, each host will have the same contents in its Pubcookie keys folder.

Note: If you don't sychronize clustered hosts, session cookies set by one cluster member will not be readable by the other cluster members, resulting in Can't unbundle session cookie error messages in the Event log.

Multiple Web Site Configuration

If a machine hosts multiple web sites (server names), additional configuration may be required.

  1. (Required) Since each web site represents a differnet server name, each web site must obtain a host key from the keyserver. Install Pubcookie for one site. Then run the keyclient again (using the -H hostname option) for each additional web site. Reset IIS when you're done.

  2. (Recommended) By default the filter reads all configuration settings starting from the main PubcookieFilter registry key. If two different web sites have different configuration objectives, then you may run into conflicts. For example, one site might have authentication enabled at the root level, while a second site might enable it only for a subfolder. You can't do both, since the AuthType settings will conflict. Therefore, you should separate configuration such that each web site has its own location for configuration settings:

    1. Using the IIS Manager, open the Properties for each web site.

    2. Select the Pubcookie Server Values tab and choose the WebVarLocation variable from the drop-down menu.

    3. Enter a new registry location for the WebVarLocation. You might base the name on the web site (e.g. System\CurrentControlSet\Services\PubcookieFilter\DefaultWebSite).

    4. Notice that your web site's IIS Instance ID maps to the WebVarLocation. You can see this in the Window registry.

    5. Once a WebVarLocation has been defined for a site, all new configuration changes will be represented under the new registry location.

Pubcookie Installer Msiexec Options

The Windows Installer package for Pubcookie supports several command-line options that can be used with the msiexec command.

  • LOGINURI (Login Server URL)

  • KEYMGTURI (Key Server URL)

  • AUTHID1-3 (Authentication Flavor Names; Use "" for unused flavors.)

  • RUNKEYCLIENT (Keyclient Behavior. 0=Do not run keyclient; 1=Obtain new key (default); 2=Retrieve old key)

For example, you might run it at the command prompt, first changing folders to wherever you saved Pubcookie.msi.

> cd C:\WINNT\system32\inetsrv\pubcookie
> msiexec /i pubcookie.msi \
    LOGINURI=https://login.example.edu \
    KEYMGTURI=https://login.example.edu:2222 \
    AUTHID1=EGNETID AUTHID2="" AUTHID3="" \
    RUNKEYCLIENT=1

Upgrading

[fixme: This is first draft. We need more real-world experience to confirm that this section is accurate.]

The Windows installer package requires you to uninstall previous versions prior to installing a newer version.

  1. Run the installer for the version of Pubcookie currently installed on your system, e.g. if you're using version 3.1.1 run the Pubcookie 3.1.1 installer.

  2. Choose the Remove option from the Program Maintenance screen, click Next, and click Remove. This will uninstall the current version while perserving your current Pubcookie keys folder and your current configuration settings for alternate WebVarLocations and web resources (i.e. web instances, folders and files).

    Note: uninstalling Pubcookie removes the root level configuration settings for the filter (i.e. Pubcookie Server Variables). These settings will be added back, based on the Site Information you provide, when you install the newer version.

  3. Once you have uninstalled the current version of Pubcookie, run the new installer. It will install Pubcookie as if from scratch, perserving your current Pubcookie keys folder and configuration settings.

    Note: Enter the same Authentication Flavor Names to ensure that current AuthType configurations work the same as before. If you change your Authentication Flavor Names, resources that currently require authentication may not be protected anymore.

    Note: The safest keyclient behavior to choose during an upgrade is to not run the keyclient. This leaves your keys folder unchanged. Retrieving the existing key is a safe choice too.

    Note: The installer will remove old versions of the filter from the IIS metabase, but this generally isn't as effective as uninstalling things first.

Uninstalling Pubcookie

[fixme: TBD. need to document effects to each installed item.]

Known Problems

Known problems with Pubcookie 3.2.1 include:

  • IIS 6.0 Inactivity Timeouts. The inactivity timeout on IIS 6 defaults to 20 minutes for each web application pool (see Properties > Performance > Idle timeout). When it times out, it's like IIS has been reset, causing the filter to reinitialize and generate a new session key (if you don't have one on disk). The new session key can't be used to read old session cookies, causing error messages for users will session cookies that predate the timeout. The Event log will show Can't unbundle session cookie errors. Uncheck idle timeout to prevent this from happening.

    [fixme: does this belong up above somewhere?]

  • Enterprise_Domain. This obsolete setting will be removed from the Pubcookie Directives configuration tab in future release. It should be ignored.

  • Event log sources. If a new web site is added after installation, its IIS Instance ID may need to be registered as an event log source pointing to the pbc_messages DLL containing the event log messages.

Appendix A: Windows Certificate Store

The Windows certificate store holds the SSL key pairs used by IIS and the Pubcookie keyclient. You can use the MMC Certificate snap-in to view and manage these certificates.

  1. Open the MMC console by clicking Start > Run

  2. Type mmc and click OK.

  3. On the Console menu, click Add/Remove Snap-in.

  4. Click Add > Certificates. You'll be asked to select from the current user account, service account, or the computer account.

  5. Choose the Computer account, which is where the relevant certificates are stored.

  6. Click Local computer, and then click OK.

  7. Use the MMC to review the certicates in the Personal container. Remove any certificates that do not belong.


[Pubcookie Home Page]
Copyright © 2002-2008 University of Washington
UW Technology Services
Pubcookie Contact Info
Modified: June 17, 2005