Installing and configuring CoSign on Windows Server 2008/IIS7

The instructions on this page cover installation and configuration of the CoSign software on an IIS7 web server running on Windows Server 2008.

Installation instructions for other types can be found using the following links:

• Apache
• Tomcat
• Windows Server2003/IIS6
• Windows Server2008/IIS7

If you simply want to use CoSign functionality on a server that already has CoSign installed and configured, you should read the instructions on using CoSign.

What is CoSign

CoSign is the Web Single Sign-On operated by ISS for use on central and departmental web servers and applications. Where possible, CoSign authenticates users (i.e. proves their identity) based on their existing credentials, so that no additional password prompts are necessary. Where this is not possible, either because there are no existing credentials, or because the browser is unable to pass them securely, the user will be prompted for his or her password just once per browser session, and the password will always be sent over a secure connection.

CoSign Web applications do not need to handle users' passwords; they are simply notified of the user's identity.

CoSign has been tested with a wide variety of browsers and operating systems, and is believed to operate correctly and securely in all circumstances.

How to install iiscosign on Windows Server 2008/IIS7

Pre-requisites

Before starting your cosign installation make sure you have the following installed/setup on your server:

• IIS7
• The domain name you wish to use
• An SSL certificate for the domain name

It is also worth checking the following particularly if you are having difficulty getting your Cosign module installation to run:

• For new Winders Server 2008 installations DO NOT copy/replace the "applicationHost.config" file from another server with cosign already installed. If you do the encryption key will be corrupted and you will have to reinstall IIS7 all over again.
• For new Windows Server 2008 installations you may need to run the following code to uninstall/reinstall .Net. Open a command prompt (Run as Administrator) and navigate to "C:\Windows\Microsoft.NET\Framework64". Choose either the "v2.0" or "v4.0" folder, depending on which version you are trying to run with cosign, then run the following code
  @REM Uninstall .Net
  aspnet_regiis.exe -u
  
  @REM Install .Net
  aspnet_regiis.exe -i
  
• Make sure there is a "web.config" file in the "wwwroot" folder and the root folder of all web sites that are to be protected by cosign.
• If your web site is running in an application pool with an account identity, the account should be a member of the IIS-IUSRS group.
• The IIS-IUSRS group should be granted "Full Access" to the root directory of your web site ONLY IF your web site directory is outside the "wwwroot" folder.
• If you are running an MVC web application you need to clean up your config files. Some developers have experienced cosign issues if there is more than one .config file.

Notation

In these instructions the following notation is used:

• domainname - this is the root domain name for your web server which will be followed by ".lancs.ac.uk". For example "mydomain.lancs.ac.uk". The domain name must have the SSL certificat associated with it.
• servername - this is the name of the web server. For example "MIS-SPRING".

Obtaining the Cosign Windows Module and Cosign Windows Filter

Installation of cosign on IIS7 requires the cosign module dll files for participation in a CoSign Single Sign-On environment. However, the download does not come with openssl.exe which is used to generate .csr files for requesting certificates. Consequenly, the cosign ISAPI filter download (a.k.a. IISCosign) usually used for IIS6 installations is also required.

• Go to http://weblogin.org/ and download the zip files for:
  • Windows Module
  • Windows Filter
• Extract these files onto the desktop of the server. They will be called cosignmodule-[version] and iiscosign-[version].
• Move the iiscosign-[version] into "C:\Program Files" and rename the folder "IISCosign".
• Within "C:\Program Files\IISCosign", create the following sub-folders:
  • SSL

Request a certificate for use with CoSign

• Follow the general instructions for creatiing a certificate request at: http://www.lancs.ac.uk/iss/tsg/cosign/csr.html
• Alternatively use the instructions for Generating a Certificate Signing Request, suitable for use with CoSign on Windows

Configure Cosign Module

• Create the directory "C:\inetpub\temp\Cosign Cookie DB" for the service cookie cache. Update the permissions for IIS_IUSRS to "Full Control"
• Open an explorer window and navigate to "C:\Windows\System32\inetsrv\config\applicationHost.config" file. Open with NotePad and add the following options.
  <configSections>     ...
      <sectionGroup name="system.webServer">
          ...
          <section name="cosign" overrideModeDefault="Allow" />
          ...
      </sectionGroup>
  </configSections>
  ...
  <system.webServer>
      ...
      <cosign>
          <webloginServer name="cosign.lancs.ac.uk" loginUrl="https://weblogin.lancs.ac.uk/?" port="6663"
              postErrorRedirectUrl="https://weblogin.lancs.ac.uk/post_error.html" />
          <crypto certificateCommonName="domainname.lancs.ac.uk" />
          <cookieDb directory="%systemDrive%\inetpub\temp\Cosign Cookie DB\" expireTime="120" />
          <!-- Note that the proxyCookies section can be ignored. Only add this line, uncommented,
              if your weblogin servers are configured to provide your web site with proxy cookies. -->
          <!-- proxyCookies directory="%SystemDrive%\inetpub\temp\Cosign Proxy DB" / -->
          <validation validReference="^https?:\/\/.*\.lancs\.ac\.uk(\/.*)?"
              errorRedirectUrl="https://weblogin.lancs.ac.uk/cosign/validation_error.html" />
          <cookies secure="true" httpOnly="false" /><!-- Use httpOnly="true" if not using HTTPS-->
          <service name="cosign-https-domainname.lancs.ac.uk" /><!-- Use "cosign-http-domainname.lancs.ac.uk" if not using HTTPS-->
          <!-- Protected Status - change to "off" if you do not want the entire domain protected -->
          <protected status="on" />
      </cosign>
      ...
  </system.webServer>
• For the validation handler to work correctly, cosign protection needs to be turned off for the "/cosign/valid" location. This can be done by adding the following XML to "C:\Windows\System32\inetsrv\config\applicationHost.config":
  <location path="Default Web Site/cosign/valid">
      <system.webServer>
          <cosign>
              <protected status="off" />
          </cosign>
      </system.webServer>
  </location>
• Open a command prompt - make sure you "Run as Administrator" and cd to your cosignmodule-[version] folder. Run the following commands:
  copy /Y x64\CosignModule.dll C:\Windows\SysWOW64\inetsrv
  
  copy /Y x86\CosignModule.dll C:\Windows\System32\inetsrv
  
  copy /Y src\Cosign_Schema.xml C:\Windows\System32\inetsrv\config\schema
  • If the copy command doesn't work then do the copy manually making sure you get the right files in the right folder.
• In the same command prompt run the following lines to add the cosign module. The command line options for removing the cosign module are also included. If appcmd.exe is not in your %PATH%, you can find it in "%windir%\system32\inetsrv". If the modules have been added correctly they will be listed in IIS7 Manager under servername -> Modules
  @REM ADD module (64-bit Application Pools)
  appcmd install module /name:"Cosign-x64" /image:"%windir%\SysWOW64\inetsrv\CosignModule.dll"
      /add:"false" /precondition="bitness64"
  appcmd add module /name:"Cosign-x64" /app.name:"Default Web Site/"
  
  @REM ADD module (32-bit Application Pools)
  appcmd install module /name:"Cosign-x86" /image:"%windir%\system32\inetsrv\CosignModule.dll"
      /add:"false" /precondition="bitness32"
  appcmd add module /name:"Cosign-x86" /app.name:"Default Web Site/"
  
  @REM DELETE module (64-bit Application Pools)
  appcmd delete module /name:"Cosign-x64" /app.name:"64-bit app"
  appcmd uninstall module "Cosign-x64"
  iisreset
  • If the "precondition="bitness" doesn't work leave it off. You should then go into the applicationHost.config and add it in as follows:
    <globalModules>
        ...
        <add name="Cosign-x64" image="%windir%\SysWOW64\inetsrv\CosignModule.dll" preCondition="bitness64" />
    </globalModules>
• Go to the IIS Manager (IIS7) and navigate to servername - > Sites -> Default Web Site (or the domainname) -> Handler Mappings. This should give you a list of the handler mapping for the web site.
• In the right hand menu click on "Add Module Mapping"and use the following values. If the change has been implemented the web.config in the wwwroot for Default Web Site should have the new values in.
  <!-- For 64 bit -->
  Request path: /cosign/valid*
  Module: Cosign-x64
  Name: Cosign Validation x64
  
  <!-- For 32 bit -->
  Request path: /cosign/valid*
  Module: Cosign-x86
  Name: Cosign Validation x86

Configuring the Test Web Site

• Create a new directory "C:\inetpub\wwwroot\CosignTest".
• Copy the files "cosignvars.aspx" and "logout.aspx" from the cosignmodule-[version] folder into "C:\inetpub\wwwroot\CosignTest".
• Load up your favorite, modern web browser and navigate to "https://domainname.lancs.ac.uk/CosignTest/cosignvars.aspx". If everything went smoothly, you should be redirected to your weblogin server to log in, and back to your cosign-protected web page. The values of your username, cosign factor and cosign service should be displayed in the page. You can view the code of these pages to see how the user information was obtained.

Configuring a Web Site

• Within each directory of a web site you can update the "web.config" to override the inherited configuration options. Because the "applicationHost.config" has <protected status="on" /> you may want close your web site to all users, but keep the welcome.html page open with the following:
  <?xml version="1.0" encoding="UTF-8"?>
  <configuration>
      <system.webServer>
          <cosign>
              <protected status="on" />
          </cosign>
      </system.webServer>
      ...
      <location path="Default Web Site/welcome.html">
          <system.webServer>
              <cosign>
                  <protected status="off" />
              </cosign>
          </system.webServer>
      </location>
  </configuration>

Authentication Factors and Compatability Mode

If your server needs to configure specific authentication factors, you'll need to add some items to the <service> tag in "C:\Windows\System32\inetsrv\config\applicationHost.config". Note that the "factor" items must all be satisfied, the "ignoreSuffix" will be matched to any factor. For more information please view the ReadMe.txt file in the cosignmodule-[version] directory.

NOTE: Running an application pool in "classic mode" may result in the server variables not being available to ASP scripts. There is a compatibilityMode option to correct this in the cosign section of the "C:\Windows\System32\inetsrv\config\applicationHost.config" config file.

Help!

All of the information for these instructions was taken from the ReadMe.txt files in both the Cosign Module and Cosign Filter directories. For further information and help please read these files and use the URLs suggested at the end of each.