Also be sure to check out the Cosign Wiki for more help.
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.Back to index
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.
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.
-----BEGIN CERTIFICATE-----Be sure the line with BEGIN CERTIFICATE is the very first line of the *.cert file.
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).
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.Back to index
The following permissions need to be set for Windows 2003 (this is not necessary for a Win2k/IIS5 setup):
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.
openssl pkcs12 -in [server.name.umich.edu.cert] -inkey [server.name.umich.edu.key] -export -out [server.name.umich.edu].p12You will be prompted for a password. Remember this password! You will need it later.
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.Back to index
If you skipped the auto-generating cert feature of the installer you can still use the openssl utility to do this.
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
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:
openssl req -new -config \SSL\sslconfig.cfg -key [server.name.umich.edu].key -out [server.name.umich.edu].csrNOTE: 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.
openssl pkcs12 -nodes -in [exported_file_name.pfx] -out [exported_file_name.pem]
-----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:
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.
Microsoft Knowledge Base article Q313299 has some more info on exporting keys.Back to index
A good place to start for an overview of how SSL works is at http://www.modssl.org/docs/2.8/ssl_intro.htmlBack to index
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\.
The location of the certificate authority file and its hash.
The location of the SSL certificate for your server.
The location of the private key file for your server.
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.
The folder where IISCoSign caches service cookies.
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.
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.
The number of backside connections the filter has ready-to-use for doing cookie CHECKs.
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.
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.
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.
You can have multiple web sites with different services or multiple web sites
with one service. Just add more
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:
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.
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.Back to index
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.Back to index
Copyright (c) 2002-2005 Regents of The University of Michigan. All Rights Reserved. See COPYRIGHT.