Included on this page:
This guide helps Microsoft IIS server administrators install the Pubcookie ISAPI
filter, herein referred to as simply the filter.
Significant improvements since version 3.0.0:
Note: some new features require a Pubcookie 3.1.0 or higher login server.
The filter relies on additional infrastructure at your site. Here are some
general prerequisites that, if fulfilled, will lead to a smooth, successful
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
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.
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
A typical installation has several stages:
The installer first allows you to decide to install Pubcookie, or to modify, repair, or remove Pubcookie if it
is already installed.
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.
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.)
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"
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
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.
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.
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.
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
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.
For the cleanest upgrade from an earlier version of Pubcookie, remove previous
versions before installing the current one.
To remove previous versions (optional):
Back up and remove your existing System32\Inetsrv\Pubcookie folder.
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.