Pubcookie ISAPI Filter - Install Guide

Note: Documentation can contain bugs too. The online version of this document is always the most up-to-date version.

Included on this page:

Overview

This guide helps Microsoft Internet Information Server administrators to install, configure and use the Pubcookie 3.3 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 changes in Pubcookie 3.3.2c:

Significant changes in Pubcookie 3.3.2b:

Significant changes in Pubcookie 3.3.1:

Significant changes in Pubcookie 3.3.0a:

Significant changes in version 3.3.0:

Significant changes in version 3.2:

Compatibility

Here are some compatibility notes for version 3.3:

Compatibility note on version 3.3 encryption options:
The version 3.3 filter supports different encryption algorithms. AES encryption is the default. However, earlier versions of the login server only support one algorithm, DES, so you will have to determine the version of your login server and set the Encryption Method directive accordingly. It may make the most sense to do this at the web site level.

Upgrading from version 3.0/3.1/3.2 to 3.3:
Servers being upgraded from version 3.0/3.1/3.2 to version 3.3 should be aware that version 3.3 expects and uses AES encryption by default. If your login server is version 3.3 or higher there is no concern; it supports authentication requests that ask for AES encrypted replies. However, to interoperate with earlier versions of the login server, you must set the Encryption Method directive to use DES encryption for your web site. This will ensure that your upgraded filter continues to use DES encryption.

If your login server is version 3.3 higher and therefore allows you to use AES encryption, you should note that session cookies encrypted with DES cannot be unencrypted with AES. As a result, session cookies obtained by users prior to upgrading the module will be invalid after the upgrade. This means some users will be redirected through the login server to establish a new session.

Clustered hosts should be upgraded with special care to keep all cluster members using the same encryption method.

Note: You do not have to request a new encryption key to use version 3.3. Your current host key works equally well for AES and DES encryption.

Upgrading from version 2.7 to 3.3:
Servers being upgraded from earlier versions of the filter (classic versions, such as version 2.7) may require configuration changes. Extra care should be given to reviewing that authentication is working as expected after the upgrade. Also review the sections on multiple web site configuration and clustered host configuration if they apply to your environment.

Servers being upgraded from earlier versions should also be aware of the switch to AES encryption noted in the compatibility notes above.

Also recall that version 2.7 requires an encryption key specific to your primary IP address. If you want to be able to rollback to version 2.7 more easily, you should keep your current key intact on your server as well as on your site's Pubcookie login server. To do so, select the option to retrieve your old key when working through the installer; otherwise it will obtain a new key from the keyserver, one that isn't compatible with version 2.7.

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.

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:

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 private 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, "The wizard was interrupted before Pubcookie3 could be completely installed", click Finish and run it again. (See Installer errors in the Known Problems section below.)

  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.

    Note: See Installer errors in the Known Problems section below if the installer is interrupted during installation.

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

Pubcookie Configuration Overview

Pubcookie derives 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 properties. 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 symmetric 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:

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

> cd C:\WINNT\system32\inetsrv\pubcookie
> keyclient.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 host 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 host 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.

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 draft text. 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 the Windows components in Pubcookie 3.3.1:

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.


Copyright 1999-2007, University of Washington. All rights reserved.
See doc/LICENSE.txt for terms of use.