IISCoSign Filter

Also be sure to check out the Cosign Wiki for more help.

Contents

Overview

IISCoSign is an ISAPI filter. It follows the container model of authentication and needs a central login server to talk to.

See the CoSign home page for more background information.

E-mail any questions or comments to cosign at umich dot edu.

Installation

Unzip the setup files then double-click on setup.exe.
Follow the prompts for installing IISCoSign.
Selecting custom will allow you to change the default install location for IISCoSign.
Custom will also allow you to select which components are installed. If this is your first time installing, it is highly recommended you install all available components.
After installation you will be prompted to generate SSL certificates. If this is selected you will then be prompted for some information that is embedded into your certificate signing request (CSR).
After certificates are generated (or you elected to skip this) you will be prompted for some configuration information. The first item is the name of your service. Whatever you type in here, "cosign-" will be prepended to it.
Login is the DNS name of the login server the filter will talk to in order to determine whether somebody is logged in. Login CGI is the URL users will be redirected to to log in.

After the installer is done, there are a few more steps necessary to finish setup.

1. Have your CSR signed.
2. For Windows 2003 servers, set permissions.
3. Add the filter to the web site(s) you want CoSign-protected.

Signing the CSR

This installer uses a certificate authority cert (the umwebca.pem file) issued to the University of Michigan. If you are not setting up a server for use in the U-M computing environment this file is useless to you. Contact the administrator for your particular institution's weblogin server to obtain an appropriate certificate authority file.

1. E-mail webmaster at umich dot edu (or the webmaster for your institution). If you chose to generate your certificates during the install you will find a file ending with the extension *.csr in your \IISCoSign\SSL folder. Open this file with Wordpad then copy-and- paste the contents into your e-mail. Include a nice message asking the webmasters to sign your csr. Also include the name of the server this certificate will be residing on as well as the name of your CoSign service.
2. When you get your signed certificate back take the 'cert' part of the e-mail and put it into the file called [my.servername.umich.edu].cert. (This file was auto-generated for you.) The cert part is the data between and including the lines:

   -----BEGIN CERTIFICATE-----
   -----END CERTIFICATE-----

   Be sure the line with BEGIN CERTIFICATE is the very first line of the *.cert file.
3. Hash your certificate authority (CA) file(s). CA certs are used by the filter to verify the identity of the Weblogin server. OpenSSL looks up a hash value associated with the CA file and uses this to do said verification. As such, here is how to hash:

   From a command prompt, run:

   openssl x509 -noout -hash -in \path\to\umwebCA.pem

   A hash value is displayed. Copy-and-paste the contents of the C:\path\to\CAFileName file into a file called <hash value>.0

   In your CoSign.dll.config file have <CAFilePath> point to the folder where the hash is located. (Whereas in the past it would point directly to the file).

4. Open up the Internet Services Manager. Stop the web site you would like to have protected by CoSign.
5. Right-click on the site you just stopped and select 'Properties.' Select the 'ISAPI Filters' tab. Click 'Add.' Browse or type in the path where you placed CoSign.dll and name it "CoSign Filter."
6. Restart the web site. It is now filtered! Try visiting your site: make sure you're properly redirected to the weblogin server and are then redirected back with authenticated access.
   NOTE: Some servers require you to restart IIS for the filter to load.

What else to do

If you didn't generate SSL certs using the installer then you have much more to do. If you want to use certificates that are in your Windows local certificate repository you will have to export your key and cert as files so that IISCoSign can use them. After that, update your CoSign.dll.config file with the appropriate file paths to the certs. You'll also need to add a service name to the file.

Setting permissions in Windows 2003

The following permissions need to be set for Windows 2003 (this is not necessary for a Win2k/IIS5 setup):

1. For your entire \IISCoSign\ folder:
   IIS_WPG needs needs everything selected except for "Special Permissions." Be sure to select the option that applies these permissions to the folder contents and sub-folders.
2. For the \CookieDB\ folder:
   Internet Guest Account, IUSR_[machine name] needs Read and Write selected.
3. For the \Logs\ folder:
   IUSR_[machine name] - Read & execute, list folder contents, Read, and Write.

Using OpenSSL certificates for https

If you already have a certificate for this purpose then you are all set. If you have your own Windows Certificate Authority setup, you can use that as well. Finally, if none of these options are available to you you can reuse your openssl generated certificate for this.

Here's how:

1. Have your webmaster sign your openssl generated CSR. (The creation of a private key and csr was done automatically for you. If you chose to skip this step in the setup see +Using Openssl.exe to create certificates+.)
2. Open a command prompt and cd to your /iisCoSign/ folder.
3. Run the following command:

   openssl pkcs12 -in [server.name.umich.edu.cert] -inkey [server.name.umich.edu.key] -export -out [server.name.umich.edu].p12

   You will be prompted for a password. Remember this password! You will need it later.
4. Run mmc.exe.
5. Open the certificates console. a. Go to File | Add/Remove Snap-in... b. Click Add... c. Select Certificates. Click Add. d. Select My Computer Account. Click next. e. Select Local Computer. Click Finish. f. Click Close. g. Select Certificates (Local Computer). Click OK.
6. Expand Certificates (Local Computer)->Personal->Certificates.
7. Right click on Certificates (the final one in the tree). Select All Tasks | Import...
8. Click next. Browse for the UMWebCA.pem file. (If you can't see the file make sure Files of Type is set to *.*) Click Ok. Click Next, Next, the Finish.
9. Right click on Certificates (the final one in the tree). Select All Tasks | Import...
10. Browse for the *.p12 file you generated in step 3. Click Next.
11. Enter the password you used in step 3. Click Next. Click Next. Click Finish.

Now when you open up IIS Manager and select Server Certificate under the Directory Security tab you can select "Assign an existing certificate" option. The certificate you just imported should be listed.

Using Openssl.exe to create certificates

If you skipped the auto-generating cert feature of the installer you can still use the openssl utility to do this.

1. Open a command prompt and cd to your IISCoSign folder. Assuming you opted to install the openssl component you should see the openssl executable in this folder.
2. 2) Run the following commands:

   openssl genrsa 1024 > [server.name.umich.edu].key
   openssl req -new -config umconfig.cfg -key [server.name.umich.edu].key -out [server.name.umich.edu].csr

3. When prompted for information, please provide the appropriate data. The common name will be the name of your server and the contact e-mail should be the e-mail of the person to be notified when the certificate is about to expire.
4. Send an e-mail to webmaster@umich.edu. Cut-and-paste the contents of the *.csr file into your e-mail.
5. Place the UmWebCA.pem file, *.key file you generated, and the *.cert file you receive from the webmaster into your C:\[CoSign path]\SSL\ folder.
6. Update your XML configuration file to point to these files. The CAFilePath item points to the umwebca.pem file. The ChainFilePath item specifies the [yourservername].cert file that you received from the U-M webmaster. The PrivateKeyFilePath item points to the [yourservername].key private key file that you generated. Be sure to include the full path such as C:\Program Files\CoSignFilter\SSL\servername.key.
7. See +What to do next+ section of this readme.

Re-signing an expired certificate

At the University of Michigan we sign our certificates for a one year period. This will probably be different for your institution or business. Generating a new certificate signing request is easy. Here's how:

1. Open a command prompt and cd to your \iisCoSign\ folder.
2. Run the following command:

   openssl req -new -config \SSL\sslconfig.cfg -key [server.name.umich.edu].key -out [server.name.umich.edu].csr

   NOTE: If you generated your certificates automatically on install, you can reuse the sslconfig.cfg file. If not, you will need to edit the umconfig.cfg file.
3. Follow the steps in +What to do next+ for having your CSR signed. You will replace the contents of your current *.cert file with the certificate sent back to you by your webmaster.

Using an existing key-cert pair from the MS certificate store

1. Using the Certificates Manager in MMC (Start Menu -> Run -> then type mmc, press enter), export your key. Make sure "Yes, export the private key" is selected. You will be asked for to create a password. Be sure to remember this password!
2. Open a command prompt, go to C:\program files\iisCoSign\ then run this command:

   openssl pkcs12 -nodes -in [exported_file_name.pfx] -out [exported_file_name.pem]

3. You will be asked for the password you used above.
4. Open the *.pem file with Wordpad.
5. The file can now be split into the private key and public certificate. The private key is designated by:

   -----BEGIN RSA PRIVATE KEY------
   -----END RSA PRIVATE KEY-----

   Copy these two lines and everything inbetween them and save them into a file such as exported_file_name.key.

   The public certificate is designated by the lines:

   -----BEGIN CERTIFICATE-----
   -----END CERTIFICATE-----

   Save these lines and everything inbetween in a separate file such as exported_file_name.cert.

   It's probably most convenient to place this in your c:\program files\iisCoSign\ssl folder.

6. Edit CoSign.dll.config to have <PrivateKeyFilePath> to point to the file containing the private key.
7. Edit CoSign.dll.config to have <ChainFilePath> point to the file containing the cert.
8. You can now safely delete the exported .pfx and .pem files.

Microsoft Knowledge Base article Q313299 has some more info on exporting keys.

More about SSL

A good place to start for an overview of how SSL works is at http://www.modssl.org/docs/2.8/ssl_intro.html

The IISCoSign configuration file

The default name for the configuration file is CoSign.dll.config. It is an XML file. IISCoSign looks for the location of the file by reading the registry value ConfigFile located at HKLM\SOFTWARE\University of Michigan\ITCS\CoSign. By default, this file is located at C:\Program Files\IISCoSign\.

• <CAFilePath>C:\Program Files\CoSignFilter\SSL\</CAFilePath>

  The location of the certificate authority file and its hash.

• <ChainFilePath>C:\Program Files\CoSignFilter\SSL\my.server.name.umich.edu.cert</ChainFilePath>

  The location of the SSL certificate for your server.

• <PrivateKeyFilePath>C:\Program Files\CoSignFilter\SSL\my.server.name.umich.edu.key</PrivateKeyFilePath>

  The location of the private key file for your server.

• <LogFilePath fileSizeInKB="4096" >C:\Program Files\CoSignFilter\Logs</LogFilePath>

  The folder where IISCoSign puts its log files and the maximum size of the log files. When the log grows to the size specified, it is closed and a new log file is started.

• <CookieDBPath>C:\Program Files\CoSignFilter\CookieDB</CookieDBPath>

  The folder where IISCoSign caches service cookies.

• <CoSignServer port="6663">weblogin.umich.edu</CoSignServer>

  The port and DNS name of the central weblogin server(s). This is where the filter makes 'backside' connections to check the validity of cookies.

• <RedirectURL>https://weblogin.umich.edu/?</RedirectURL>

  If a user is not logged in this is the URL they are sent to for logging in. You'll notice that the '?' means the user is being redirected to a CGI. The part after the ? is constructed by the filter.

• <ConnectionPool size="4" />

  The number of backside connections the filter has ready-to-use for doing cookie CHECKs.

• <CookieDBExpireTime seconds="60" />

  The amount of time a cookie in the server's local cookie cache is considered good. When the cached cookie's last time stamp is greater than this value, the filter talks to the central login server to see if the user is still logged in. If the user is still logged in then the timestamp is updated. If the user is no longer logged in, then the user is redirected to the login page.

• <WriteDataToEventViewer>FALSE</WriteDataToEventViewer>

  Probably best left to FALSE. If you are having trouble running the IISCoSign filter you can set this to TRUE to send logging information to the Windows Event Viewer. This is recommended only as a last resort since IISCoSign is quite verbose and will fill up your logs quickly. You can also open a debug viewer such as dbmon.exe or DebugView to see what IISCoSign is up to.

• <CheckIPAddr>FALSE</CheckIPAddr>

  By setting this to TRUE IISCoSign will check that a service cookie is from the same IP address each time. Setting this to FALSE allows IISCoSign to work with hardware load balancers.

• <Service website="my.server.name.umich.edu">CoSign-YOUR_SERVICE_NAME_HERE
   <Protected>/secure</Protected>
   <Protected allowPublicAccess="TRUE">/test1</Protected>
   <Protected>/test2</Protected>
   <Protected>/protected_page.html</Protected>
  </Service>
  

  You can have multiple web sites with different services or multiple web sites with one service. Just add more <service> tags. To make a resource CoSign protected, create as many <Protected> tags under the <Service> tag as you'd like. By default, protecting something like /test1 will also protect all URLs and pages underneath /test1 -- such as /test1/script.asp, /test1/images/pic1.jpg, and /test1/more/info/.

  Currently, the website="" relies on the SERVER_NAME variable to determine if a web site is protected. THIS IS INSECURE WITH THE DEFAULT IIS SETTINGS. If you are using the website value you should also using IIS's 'Advanced Web Site Identification' feature to locally bind the DNS name of your server to an IP address. An alternative to using website="" is to use IISDescription. For example:

  <Service IISDescription="Default Web Site">CoSign-YOUR_SERVICE_NAME_HERE
  ...
  </Service>
  

  This setting relies on the name of the web site used by IIS and uses the INSTANCE_ID server variable to lookup the web site name in the metabase. Be sure the value for IISDescription is exactly the same, including spaces, as it appears in the metabase.

  The allowPublicAccess option can be set to TRUE or FALSE. By default, the value is FALSE. By setting this to TRUE a web page or URL can be viewed by anybody. However, if a user has already logged in AND visited a protected page then the CoSign variables HTTP_REMOTE_USER and HTTP_REMOTE_REALM will be added by the filter. The idea is that web applications can check for these variables, and, if present, can customize a page for a user if he's logged in or showing a generic page if he is not. The value HTTP_CoSign_SERVICE variable is always populated whether a user has authenticated or not (and is visiting a protected URL).

  Unlike the Apache filter you cannot have 'alternating protection' such as /a/b/c/d where /a is protected, /a/b is not, /a/b/c is, and so on.

More help

Join the e-mail list, cosign-discuss at umich dot edu.

Send questions to the developers, cosign at umich dot edu.

Read the archived announcements and discussions.

Compiling IISCoSign

IISCoSign is distributed with a precompiled binary. If you're interested in building IISCoSign yourself, here is a basic outline of the different things you'll need.

This project was created using Microsoft Visual Studio.NET 2003

The source code is available from the CoSign web site .

You will also need libsnet, OpenSSL, and MSXML 4.0.

Libsnet is available via anoymous CVS from http://rsug.itd.umich.edu.

OpenSSL can be downloaded from http://www.openssl.org.

MSXML 4.0 is available from Microsoft's web site.