Included on this page:
This guide walks you through the process of adding Pubcookie to your Microsoft Internet Information Server at the University of Washington. Instructions are specific to the way that Pubcookie is deployed at the UW.
Here are the significant changes introduced in Pubcookie ISAPI Filter 2.7.x:
supports per-application logout features via the new Logout_Action registry setting; see Configuring Logout for Pubcookie-Protected Websites for details;
better control over application boundaries via the new AppID registry setting;
new handling of run-time configuration settings - most registry settings now can be added to any resource and only those that affect the ISAPI filter's baseline operations require a reset; review the new Windows Registry Settings reference for details;
For a complete list of changes, refer to the Version_History.txt file included in the distribution itself.
Version 2.7.x is backwards compatible with all previous versions of the Pubcookie ISAPI Filter. You should be able to upgrade a working configuration simply by swapping in the new DLL and bouncing the server. No need to get a new c_key. No need to change any registry settings. Existing applications should go on working the same.
Refer to Upgrading to Pubcookie ISAPI Filter 2.7.x for step-by-step upgrade instructions.
Before you begin:
Make sure your server meets all of the system requirements. Accurate system time is particularly important.
Verify that SSL connections to your Web site are working by opening: https://<your domain name> This is also very important.
C&C SSL Certificate Policy:
For use with Pubcookie at the UW, servers must have a SSL server certificate signed by either:
a well-known public CA such as Thawte (purchasing tips here), DST, or Versign;
or one signed by the UW Services CA.
All application servers require an encryption key file which can be obtained from C&C. If you are upgrading from a previous version of Pubcookie, you do not need to request a new key; your existing key will work fine as long as your IP address has not changed.
To obtain a crypt key file (c_key) for your IIS server:
Determine the IP address of your IIS server. This is very important. If it has multiple network interfaces, you need to choose the IP address at the top of the binding order. If it is a node in a Windows Load Balancing cluster, you need to use the IP address for each node based on its IP address.
(Optional) Verify that you determined the correct IP address by running gethostip.exe found in the tools subfolder of the Pubcookie distribution. This DOS command-line utility will tell you what IP address the Pubcookie ISAPI filter wants to use.
Request a crypt key file (c_key) for your server from pubcookie@u.washington.edu. Include your name, phone number, and the IP address and domain name of your IIS server.
When you receive your encryption key from C&C, continue with the setup of Pubcookie's supporting files:
Download the latest Pubcookie ISAPI Filter 2.7.x distribution.
Double-click the self-extracting zip archive. This will extract the distribution into a folder of your choice. The default is C:\Pubcookie. Make a note of the folder you choose; the instructions that follow refer to this folder.
Place your c_key file into the C:\Pubcookie folder. Note: there is no filename extension to this file.
Download pubcookie_granting.cert and place it into C:\Pubcookie. This certificate contains the public key for the Pubcookie login server run by C&C, also known locally as the UW NetID "weblogin" service.
Edit Make_Session_Key.bat, adjusting, if necessary, the HOME and OPENSSL_CONF path locations.
Run Make_Session_Key.bat. It will generate a new keypair used by Pubcookie to protect session cookies.
Edit PubcookieFilter_Install.bat. It is unlikely that you will have to change anything, but look it over so you know what it does.
Run PubcookieFilter_Install.bat. It will create a new folder within your System folder called:
%Systemroot%\System32\Inetsrv\Pubcookie |
It also copies all the supporting files to this folder.
Remove Everyone access to this folder, then add System read and Administrator change control.
Copy PubCookieFilter-2.7.x.dll from the distribution folder to:
%Systemroot%\System32\Inetsrv\Pubcookie\PubCookieFilter-2.7.x.dll |
Make sure this file has SYSTEM execute permission. It needs to be executable by IIS.
To add the Pubcookie ISAPI Filter to your Web site under IIS:
Start the Internet Service Manager (usually found in your IIS program folder).
Right-click on the Web site into which you want to install the Pubcookie ISAPI Filter. Select Properties from the popup menu.
In the ISAPI Filters tab, click Add....
Enter Pubcookie 2.7.x for Filter Name.
For Executable, click Browse... and locate the Pubcookie DLL you copied moments ago (e.g. %Systemroot%\System32\Inetsrv\Pubcookie\PubCookieFilter-2.7.7.dll).
Click OK. And click OK
Right-click your Web site. Stop and restart it.
Verify that Pubcookie is installed by reviewing the Properties of your Web site again. The status of the Pubcookie ISAPI filter should be loaded; the arrow should be up and it should be green.
(Optional) If you have multiple Web sites under IIS, and want to use Pubcookie with two or more, make a copy of the PubCookieFilter.dll for each - this is in order to avoid any conflicts that may arise due to multi-threading. For example, make PubCookieFilter1.dll, PubCookieFilter2.dll, etc. Here the number should match the Web number. Note: If debugging is turned on under these circumstances, a unique Debug Trace log will be created for each Web instance with the default filename of %Systemroot%\System32\LogFiles\PubcookieFilter<instance#>
Installation is complete. Close the IIS management console.
The built-in configuration settings for the Pubcookie ISAPI Filter should be sufficient to use Pubcookie at the University of Washington. You may want to return to this section later, if you decide that you want to change the configuration for specific applications or your entire Web site.
To change the configuration of the Pubcookie ISAPI filter:
Review the special Windows Registry Settings used to configure the Pubcookie ISAPI Filter.
Change or add new values to your Windows registry.
If you modify any of the "filter variable" settings, such as Debug_Trace, that apply to the Pubcookie ISAPI itself you will need to do a filter reset to read the new registry settings. To do so, start a Web browser and open /pubcookiefilter_reset on your IIS server. For example:
http://appserver.washington.edu/pubcookiefilter_reset |
Stopping and restarting your Web site has the same effect.
Note: see PubcookieFilterSample.reg from the distribution for example configuration settings.
The Pubcookie distribution comes with a sample application you can use to test the Pubcookie ISAPI Filter and its ability to authenticate users via the local Pubcookie login server. Here's how:
Double-click WebApp.reg from the Pubcookie distribution to add some registry settings for a sample application. (Open it with NotePad if you want to have a look at it first.)
Copy the WebApp folder, also found in the distribution, from C:\Pubcookie to your Web site's root folder (e.g. C:\inetpub\wwwroot\WebApp). Note: you can think of each folder in your server's Web root as a separate "application".
Start a Web browser and open /webapp/uwnetid/ on your IIS server. For example:
https://appserver.washington.edu/webapp/uwnetid/ |
Note: This is literal - don't substitute "uwnetid" with your UW NetID. The Pubcookie ISAPI Filter requires authentication when it matches special subfolder names. A "uwnetid" subfolder authenticates using UW NetID and password. A "securid" subfolder adds two-factor SecurID authentication. If you want to apply authentication to a whole Web site or to an entire application (remember, that's a folder in your root Web) use the AuthType registry setting to do that.
When Pubcookie is triggered, you will be redirected to the UW NetID "weblogin" service. After being authenticated, you should be redirected back to the "Webapp" application and its Default.asp, to which Pubcookie provides several server variables:
| Server Variable | Description |
|---|---|
HTTP_PUBCOOKIE_USER |
visitor's authenticated UW NetID |
HTTP_PUBCOOKIE_APPID |
application id = first directory name (e.g. webapp) |
HTTP_PUBCOOKIE_CREDS |
credential level, 1=uwnetid, 3=securid |
HTTP_PUBCOOKIE_SERVER |
hostname of the web server |
Verify that the correct information is displayed by Default.asp. In particular, your UW NetID should be displayed by this application.
Select the recommended logout link at the bottom of this page to invoke a logout request. It should redirect you to the "weblogin" service for a response.
Voila! That's Pubcookie!
If you don't like the idea of a bunch of unused files residing on your server, you can discard the Pubcookie distribution files and folder (e.g. C:\Pubcookie). Before you do, you should make a backup copy of your c_key file and safely store it elsewhere in case you need it in the future.
