Included on this page:

• Objectives
• Prerequisites
• Download and Unzip Win32 Distribution
• Verify SSL Private Key Size (1024 bits required)
• Export SSL Cert and Private Key
• Setup Supporting Files and Registry Settings
• Request Encryption Key (Using Keyclient.exe)
• Add PubcookieFilter.dll to Your Website
• Test Pubcookie (with sample WebApp)

Objectives

This guide helps you install the Pubcookie ISAPI Filter on Microsoft Internet Information Server. Objectives include:

• how to export your SSL certificate and private key using the Certificate Export Wizard
• how to setup and use the Pubcookie keyclient to obtain an encryption key
• how to add the Pubcookie ISAPI Filter to IIS
• how to test the Pubcookie ISAPI Filter to confirm that authentication works

Prerequisites

It is assumed that someone has already deployed a Pubcookie 3.0 login server and keyserver:

• If you deployed your own Pubcookie login server, locate your granting certificate (e.g pubcookie_granting.cert). It is one of the supporting files you'll need for your application server.

• If you didn't deploy your Pubcookie login server (e.g. weblogin.example.edu), contact the people at your institution who did . They will have information about obtaining your login server's granting certificate and may have further advice for setting up your application server.

• The SSL server certificate for your application server must be signed by a Certificate Authority trusted by your Pubcookie keyserver.

System requirements for your IIS machine are:

• Microsoft Windows NT 4.0 SP3 or later on Intel platform
• Microsoft Internet Information Server (IIS) 4.0 or 5.x
• SSL enabled Web site, using a 1024-bit private key
• Accurate system time
• A domain name (e.g. appserver.example.edu) registered in DNS within same subdomain as your Pubcookie login server (e.g. weblogin.example.edu)

Download and Unzip Win32 Distribution

1. Download the Pubcookie ISAPI Filter distribution.

2. Unzip the distribution, extracting the files to:

   C:\Temp

   This is the location assumed below. Among the files included are: keyclient.exe, openssl.exe, pubcookiefilter.dll, and some files to help with the installation process.

Verify SSL Private Key Size (1024 bits required)

To begin, verify that your SSL key is 1024 bits:

1. Perhaps the simplest way to verify this is to open an "https" connection to your website and ask your browser to display the details of the certificate.

2. If your SSL key is not 1024 bits, you will need to replace your current SSL certificate to work with Pubcookie. Generate a new CSR (certificate signing request) based on a 1024-bit private key (the default is 512 bits, so be sure to up this to 1024) and have your Certificate Authority sign a new certificate. Install the new certificate and then continue.

Note: Pubcookie requires a 1024-bit private key!

Export and Convert SSL Certificate and Private Key

To export your SSL cert and private key:

1. Bring up the IIS management console.

2. Select your web site, click Properties.

3. Select Directory Security tab.

4. Click View Certificate...

5. Select the Details tab, click Copy to File...

6. Follow the Certificate Export Wizard:
   1. click Next
   2. select Yes, export the private key;
      click Next
   3. select PKCS #12 (.PFX);
      check Enable strong protection;
      click Next
   4. type and confirm password;
      click Next
   5. enter a File name, e.g. C:\Temp\appserver.pfx;
      click Next
   6. click Finish
   7. click Ok if the export was successful.

The intended result of all this is a PFX-formatted file appserver.pfx containing your SSL certificate and private key.

To convert to PEM format from PFX:

1. Open a command prompt.

2. Run the following:

   cd C:\Temp openssl pkcs12 -in appserver.pfx -out appserver.pem -nodes

   This will produce appserver.pem right where you want it.

To separate your SSL certificate and private key:

1. Open appserver.pem in WordPad.

2. Use WordPad to extract the RSA private key into a new file called pubcookie_session.key.

3. Use WordPad to extract the certificate into a second new file called pubcookie_session.cert.

4. Save both new files in C:\Temp where the rest of the files reside.

Setup Supporting Files and Registry Settings

To assemble the remaining required files:

1. Get a copy of pubcookie_granting.cert from your Pubcookie login server and place it in C:\Temp.

2. Get a copy of the file containing your Certificate Authority's certificate and place it in C:\Temp, e.g. C:\Temp\cacert.pem. These instructions assume the use of a CA cert file, rather than a directory, to establish the keyclient-keyserver trust. Further work needs to be done to test and document setup using a directory of possible CA certificates.

To install the supporting files in your Pubcookie directory:

1. Edit PubcookieFilter_Install.bat in C:\Temp to see what it does and to adjust any file names if need be. Save it.

2. Double-click PubcookieFilter_Install.bat to run it. It will copy all the supporting files from C:\Temp to a new Pubcookie folder in your System root called:

   %Systemroot%\System32\Inetsrv\Pubcookie

3. Remove Everyone access to this folder, then add SYSTEM read and Administrator change control security settings.

4. Make sure the PubcookieFilter.dll in the Pubcookie folder is executable by SYSTEM accounts.

To prime the Windows registry with site-specific settings:

1. Edit the example.reg in C:\Temp. Site-specific changes should be made to several settings, which are represented in example.reg by the following lines (extracted):

   "AuthTypeName1"="FooID" "Keymgt_URI"="https://weblogin.foo.edu:2222" "Login_URI"="https://welogin.foo.edu" "Enterprise_Domain"=".foo.edu" "AuthType"="FooID"

   Refer to the Pubcookie ISAPI Filter Windows Registry Settings document for further explanation of these settings.

   While you're editing example.reg, be sure to give the "WebApp" application an AuthType setting so that it requires authentication. example.reg comes with it already defined, but you might want to fiddle with the values of the AuthTypeName1 string and corresponding AuthType string. Since AuthTypeName1 defines the string used as the AuthType value, they will be the same (e.g. "FooID" above and in example.reg).

2. Double-click example.reg to enter your settings into the Windows registry.

Request Encryption Key (Using Keyclient.exe)

To obtain an encryption key for your application server:

1. Open a command prompt.

2. Run the following:

   cd C:\Temp keyclient -c pubcookie_session.cert -k pubcookie_session.key -C cacert.pem

   Substitute file names appropriately. The keyclient looks in the keys subfolder of your pubcookie directory for these files.

3. If successful, keyclient will deposit a new DES key in your Pubcookie folder, e.g.

   %Systemroot%\System32\Inetsrv\Pubcookie\keys\appserver.example.edu

4. If unsuccessful, look into your system event log for an explanation why it failed.

Add PubcookieFilter.dll to Your Website

To add the Pubcookie ISAPI Filter to your default website in IIS:

1. Start the Internet Service Manager (usually found in your IIS program folder).

2. Right-click on the Web site into which you want to install the Pubcookie ISAPI filter and select Properties from the popup menu.

3. In the ISAPI Filters tab, click Add.

4. Enter Pubcookie for Filter Name.

5. Click Browse and locate the Pubcookie DLL for Executable (e.g. %Systemroot%\System32\Inetsrv\Pubcookie\PubcookieFilter-3.0.0.dll).

6. Click Ok. And click OK

7. Right-click your Web site. Stop and restart it.

8. Verify that Pubcookie is installed by reviewing the Properties of your Web site. The status of the Pubcookie ISAPI filter should be loaded; the arrow should be up and green.

Test Pubcookie (with sample WebApp)

A sample application has been provided to test the ISAPI filter's ability to authenticate against your configuration, to create a session, and to terminate the session through Pubcookie's logout features. To do the test:

1. Copy the sample WebApp folder from C:\Temp to your Web site's root folder (e.g. C:\inetpub\wwwroot\WebApp).

   You can think of this as creating a Pubcookie-protected application called WebApp. The example.reg used earlier assigns an AuthType setting to this application as well as others for logout.

2. To test authentication, start a Web browser and open /WebApp/ on your IIS server. For example:

   https://appserver.example.edu/Webapp/

   You should be redirected to your Pubcookie login server. After being authenticated, you should be redirected back.

3. Verify that the response generated by /WebApp/Default.asp displays the correction information. In particular, the Pubcookie User, as obtained thru the HTTP_PUBCOOKIE_USER variable, should display your id. If so, Bob's your uncle as far as authentication and seesion creation goes.

4. Now try to logout by selecting one of the logout links provided by Default.asp. For example, click invoke app-logout-and-redirect. This will make a request to:

   https://appserver.example.edu/Webapp/app-and-redirect-logout/

   Since this folder has been configured with a Logout_Action registry setting by example.reg, it will clear your current session cookie. In this case, the value assigned in the registry also causes you to be redirected to your login server, which, if all goes correctly, will serve a logout response page.