Included on this page:

• Overview
• What's New
• Prerequisites
• System Requirements
• Install Pubcookie
• Configure Pubcookie
• Clustered Host Configuration
• Multiple Web Site Configuration
• Cross-Domain Relay Configuration
• Upgrading

Overview

This guide helps Microsoft IIS server administrators install the Pubcookie ISAPI filter, herein referred to as simply the filter.

What's New

Significant improvements since version 3.0.0:

• New Pubcookie.msi installer.
• New IIS MMC extension for GUI-based configuration tabs.
• Virtual host support
• Cross-DNS-domain relay
• New No_Prompt directive
• Enhanced Session_Reauth with grace time
• New keyclient -G option to download granting certificate
• Improved OpenSSL compatibility
• Revised, improved documentation

Note: some new features require a Pubcookie 3.1.0 or higher login server.

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

• Determine how your site distributes its Pubcookie "granting" certificate. The installer needs a copy of this certificate to verify the "granting" cookies signed and sent by your site's login server. The installer may be able to download it from your keyserver, or you may have to obtain it manually. Ask your administrator which method to use.

Note: Review the sections on virtual host 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).

  Note: If your server doesn't share a common DNS subdomain (e.g. .example.edu) with your site's Pubcookie login server (e.g. weblogin.example.edu) or if your enterprise domain is in a country code top-level domain (e.g. example.ca) you will have to install and use the Pubcookie relay cgi to authenticate across DNS domains. Review the relay configuration section now to prepare for this case.

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

Install Pubcookie

Open the pubcookie.msi package as the administrator user or as an account with administrator privileges. The installer needs to create folders and files in the System32\Inetsrv folder as well as to stop and start system services.

A typical installation has several stages:

1. The installer first allows you to decide to install Pubcookie, or to modify, repair, or remove Pubcookie if it is already installed.

2. During installation, the Site Information screen collects site information. Here you'll be able to specify your server name, Pubcookie login server and keyserver locations, enterprise domain, and authentication types.  Make sure that your server name matches the certificate you installed when you set up SSL for your web site. 

3. The Custom Setup screen lets you select the ISAPI Filter and basic test Webapp for installation. You may change the installation directory and change installed components. (If you need to use the Pubcookie relay, select it to be installed; it is unselected by default.)

4. The installer is now ready to do the install. Click the Install button. The installer will add the Pubcookie filter to the IIS root filter list and restart IIS services. It will aslo use your server name to locate your SSL key pair from the Personal Certificate store and use them, along with your installed Certificate Authority certificates, to negotiate a symmetric key from your keyserver and download your site's "granting" certificate.

Note: to request a key from your keyserver you may have to ask your keyserver administrator to "permit" your host. Also, you'll need to be able to verify the keyserver's SSL certificate with the CA certificates installed on your system. Ask your keyserver administrator if you need a special CA certificate to do that.

Configure Pubcookie

Use the IIS Service Manager to modify the configuration directives specific to Pubcookie. After installation, your web site's Properties sheet will have tabs for Pubcookie Server Values and Pubcookie Directives. Each resource under the web site will have its own Pubcookie Directives tab too. Examine the properties of the WebApp example application. The values you provided to the installer will be the basis for what you initially see.

Clustered Host Configuration

For clustered host configurations, run the installer on each host. After running the install on the last host, copy the symmetric key (by default from System32\Inetsrv\Pubcookie\keys\) on the last host installed to each of the other hosts. This will syncronize the cluster with the key stored on the login server.

Multiple Web Site Configuration

If clients can connect to multiple web sites on your server (i.e., using more than one server name, each SSL enabled) you will need to run keyclient.exe for each of the names in addition to the one you specified during the installation process.  By default, keyclient.exe resides in System32\Inetsrv\Pubcookie\.  The syntax to request an encryption key for a web site is:

keyclient -H <hostname>

where <hostname> is replaced with your target web site name. Since Pubcookie uses SSL encryption, and the keyclient uses your web sites's certificate pair, you will need to have SSL access properly set up for each web site in the multiple web site scenario.

Additionally, to avoid conflicts between configuration directives, each web site can be assigned its own location in the Pubcookie directive database for its settings. Using the IIS Service Manager, open each site's Properties dialog. Here you will find the Pubcookie Server Values tab. Change the WebVarLocation variable from its inherited default value to one specfic to each web site (e.g. System\CurrentControlSet\Services\PubcookieFilter\MySiteSettings).

Cross-Domain Relay Configuration

To install the optional Pubcookie relay for cross-DNS-domain authentication, select the Relay component from the installer's Custom Setup screen. If selected, the installer adds it to your default website in PBC_RELAY in your web root folder. This folder contains the relay cgi executable itself and some necessary templates. The relay cgi picks up default configuration settings from those provided to the installer. The most significant being the location of your login server.

To configure a resource that needs to use the relay (presumably because it's located across DNS domains and therefore can't be used directly), use the IIS Service Manager to modify the resource's configuration, specifying the relay as your login server and an enterprise domain localized for the occasion.

For example, if your application server name is remote.site.org and the relay is installed as PBC_RELAY at the root of your website, open the Properties window for the resource (you might try this on the test WebApp folder) in the IIS Service Manager and select the Pubcookie Directives tab. Set the "Login_URI" directive to point to the relay cgi on your application server, e.g., https://remote.site.org/pbc_relay/index.cgi?domain=.site.org, and set the "Enterprise_Domain" directive to .site.org.

Now the filter will redirect users to the relay first. Then the relay will handle getting them to the remote login server and back again.

Note: The relay accepts the domain argument to allow a single relay to serve multiple servers and mulitiple domains. It should match your Enterprise_Domain value because the relay and the module need this to synchronize their cookie scoping. In the typical case it can be set to the enterprise domain you would have used if the login server had been in the same domain as your application server (i.e., .site.org in the example above). If your application server is in a country code top-level domain (e.g., site.subdomain.example.ca) then it must be adjusted; you can use the immediate subdomain (i.e., domain=.subdomain.example.ca) or if the resource and relay reside on the same server, use the server name itself (i.e., domain=site.subdomain.example.ca). Just be sure to synchronize it with your Enterprise_Domain value.

Upgrading

For the cleanest upgrade from an earlier version of Pubcookie, remove previous versions before installing the current one.

To remove previous versions (optional):

1. Stop IIS.

2. Back up and remove your existing System32\Inetsrv\Pubcookie folder.

3. Start IIS.

Then run the installer for Pubcookie 3.1

Note: the installer won't overwrite the web properties (registry settings) you've assigned to your website, folders, or resources. It will however update the filter variables according to the login server and keyserver URLs you provide to the installer.