How to Install the IIS Filter
About the IIS Filter Version
This documentation is for version 1.1.1 of the filter.
Some of it is based on Windows® 2003/IIS 6; Windows® 2000/IIS 5 may differ.
- What's new in version 1.1.1?
(From the original mailings to the cosign announcement list:
[1],
[2]).
Downloading
From the CoSign home page, select
the "download" link on the left side of the page. Once there, you should find the zipped file in the "Windows Filter" section of the page.
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 generate SSL certificates now, 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.
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 email
about it to root@aset.psu.edu so that it can be added to the list.
As of May 1, 2006, the CA for our CoSign server is the Thawte Premium Server CA:
if you don't have
that certificate, you can download a copy from here,
and save it in the folder you specify for the CAFilePath
tag in the Cosign config file.
The file must be named c33a80d4.0
.
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 an internal site), with the filter installed on the
C: drive, might be:
(Features new/changed in version 1.1.1 are marked like this:)
<Cosign>
<CAFilePath>C:\Program Files\IISCosign\SSL\</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>
<HttpsOnly>FALSE</HttpsOnly>
<Service website="www.dept.psu.edu">cosign-www.dept.psu.edu
<Protected>/</Protected>
<Protected allowPublicAccess="TRUE">/public</Protected>
</Service>
<Service IISDescription="Internal Site">cosign-internal.dept.psu.edu
<Protected>/</Protected>
</Service>
</Cosign>
Where
| CAFilePath |
The directory which contains your CA certificate(s).
If upgrading from an earlier version, see the What's New
page about how this has changed.
|
| ChainFilePath |
Your certificate
|
| PrivateKeyFilePath |
Your certificate's key
|
| LogFilePath |
Location and maximum size of log
files
|
| CookieDBPath |
Location of Service Cookies
|
| CosignServer |
The PSU CoSign server -- must
use these values
|
| RedirectURL |
PSU specific value -- must use
(don't forget the trailing "?")
|
| ConnectionPool |
Number of connections the filter
will use to the CoSign servers
|
| CookieDBExpireTime |
How long, in seconds, before a
cookie has to be revalidated
|
| WriteDataToEventViewer |
For debugging.
Leave as FALSE
|
| CheckIPAddress |
Set TRUE to have filter check IP
address in cookie, FALSE for either multiple servers (load balancing),
or to allow a roaming laptop to re-use its cookie as it hops networks
(e.g., from wired to wireless).
Should usually leave set to FALSE (default).
|
| HttpsOnly |
Set FALSE (default: TRUE)
to allow browser connections over an unsecure connection.
|
| Service |
One for each website that your
server is using with the filter.
The string after the tag (starts with cosign-) is the CN
of your certificate (usually also your
host's DNS name).
There are two ways to identify the particular web site: website or
IISDescription.
The value for website is
usually the site's DNS name,
while IISDescription is the actual Description as set in the IIS Manager
(since it's independent of any IP address changes, possibly a better choice).
If you're using website, be sure to
locally ‘bind’ the server's IP address to the website name.
|
| Protected
|
One entry for each section of
the site (from that point down) you want the filter to protect.
If protecting the entire server, a single entry of "/" is all that's
needed.
do not
add a trailing slash "/" to the value.
The allowPublicAccess attribute allows a area on a Web site to be accessible by anyone, logged in or not (i.e., deferring authentication decisions to other parts of the server). If they're logged in, the USER and REALM variables are set (the COSIGN_SERVICE variable
is set in either case). The default value is FALSE.
|
Activating the Filter
Open up the Internet Services Manager. Stop the web site you would like to have protected by CoSign, then:
- Right-click on the site you just stopped, select Properties
- Select the ISAPI Filters tab
- Click Add
- 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.
Some servers require you to restart IIS for
the filter to load properly.
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" )
A sample VBScript page which displays those variables, which you can install on your server.
|
