Software Versions

This documentation is for version 1.0.0 of the filter. Some of it is based on Windows 2003/IIS 6; Windows 2000/IIS 5 may differ.

Downloading

From the CoSign home page, select the "download" link on the left side of the page. Once there, find the "Older Versions" section of the page, and download the appropiate version.

Installing the IIS Filter

The IIS filter is a zipped Installer. Extract the contents to a temporary folder and launch setup.exe. When the installer asks if you wish to install certificates, answer no.

Penn State web administrators have had success with IIS 6/Windows® 2003 and IIS 5/Windows® 2000.

If using Windows® 2003, pay close attention to the extra steps dealing with permissions in the README.txt (the developers plan to fix the installer in a future release).

The installer incorrectly installs one key in the registry, you'll have add another one.

At

HKEY_LOCAL_MACHINE\SOFTWARE\University of Michigan\ITCS\Cosign

add a string value named:

ConfigFile

and set it to the full path where config.dll.config is located (e.g., C:\Program Files\IISCosign\cosign.dll.config). (You should see a similarly named key, ConfigPath, in that location, also set to that path.)

Certificates

Your Certificate

As mentioned previously, the CoSign filter needs its own certificate and key for the connection to the CoSign servers. However, if you already have a certificate (with its key) from a Certificate Authority, it can be reused for this purpose. If your only copy of the certificate and key are in the Windows Certificate store, you can export both of them with these steps.

Place a copy of the certificate and key files into the appropriate locations for your filter. Configuration options allow you to place them anywhere, but the default locations work well. For the IIS filter, that would be:

\Program Files\IISCosign\SSL\

If you don't have a certificate yet, and would like a one from a Certificate Authority (CA) already configured into common browsers, see our Penn State SSL Certificate Group Purchase Program for buying a low-cost Thawte certificate. If you'd prefer a free certificate, look into the ones available from CAcert.

Certificate Authorities

Your server's filter needs to have a copy of the Certificate Authority (CA) for the CoSign server's certificate, and the CoSign server needs to have a copy of the CA for your certificate. This allows the encrypted connection between them to use mutual authentication.

The CoSign server currently knows these public CAs:

• Thawte Premium Server CA
• Thawte Server CA
• CA Cert Signing Authority
• VeriSign International Server CA - Class 3
• RSA Data Security, Secure Server Certification Authority

If your certificate was signed by another public CA, send an e-mail about it to root@aset.psu.edu so that it can be added to the list.

The CA for our CoSign server is the Thawte Server CA: if you don't have their certificate, you can download a copy from here, and save it in the same folder as your certificate.

Registering your Certificate

Not only does the CoSign server need to know the CA for your certificate, it also needs to know the Common Name (CN) of it. If you're using the web server certificate, that's just the full host name of your server. Send an e-mail to root@aset.psu.edu with the CN and contact information (for notification purposes).

IIS Filter Configuration

The configuration information for the IIS filter is located in an xml-structured text file named:

\Program Files\IISCosign\cosign.dll.config

The file can be edited with any text editor (e.g., Notepad, Wordpad).

The values for a sample configuration for a server called www.dept.psu.edu, with the filter installed on the C: drive, might be:

<Cosign>
        <CAFilePath>C:\Program Files\IISCosign\SSL\ThawteServerCA.pem</CAFilePath>
        <ChainFilePath>C:\Program Files\IISCosign\SSL\www.dept.psu.edu.cert</ChainFilePath>
        <PrivateKeyFilePath>C:\Program Files\IISCosign\SSL\www.dept.psu.edu.key</PrivateKeyFilePath>
        <LogFilePath fileSizeInKB="4096">C:\Program Files\IISCosign\Logs</LogFilePath>
        <CookieDBPath>C:\Program Files\IISCosign\CookieDB</CookieDBPath>
        <CosignServer port="6663">webaccess.psu.edu</CosignServer>
        <RedirectURL>https://webaccess.psu.edu/?</RedirectURL>
        <ConnectionPool size="4" />
        <CookieDBExpireTime seconds="60" />
        <WriteDataToEventViewer>FALSE</WriteDataToEventViewer>
        <CheckIPAddress>FALSE</CheckIPAddress>
        <Service website="www.dept.psu.edu">cosign-www.dept.psu.edu
                <Protected>/</Protected>
        </Service>
</Cosign>

Where

Activating the Filter

Open up the Internet Services Manager.

Stop the Web site you would like to have protected by CoSign, then:

1. Right-click on the site you just stopped, select Properties
2. Select the ISAPI Filters tab
3. Click Add
4. Browse or type in the path where you placed Cosign.dll and give it a relevant name (e.g., WebAccess Filter).

Restart the Web site, it should now be filtered. Try visiting your site: make sure you're properly redirected to the WebAccess server and are then redirected back with authenticated access.

Performing Authorization Checks

The filter only provides basic authentication: that an active account has successfully logged into the WebAccess server. While it makes information about the specific session available to IIS, the filter itself does not do any further checking. Specifically, it does not check which account was authenticated, nor the realm of the account; these types of authorization (authZ) checks must be done elsewhere.

We are aware of a couple of different ways to perform authZ:

• If you're already using Server-side scripts (ASP, etc.), just get the values of the variables set by the filter (see below for sample) and check against i.e., a local file, a local database, etc.
• On Windows 2003/IIS 6: Using the URL Authorization, part of the Authorization Manager. There's information on a sample implementation that uses an Access database here.

Accessing Variables from ASP

To fetch the current values of the account name and realm, the VBScript code would be:

Request.ServerVariables( "HTTP_REMOTE_USER" )
Request.ServerVariables( "HTTP_REMOTE_REALM" )

The value for the Access Account realm is dce.psu.edu.