Cosign Setup for Microsoft IIS

This document details how to set up Cosign authentication for Microsoft Internet Information Services (IIS). The following instructions use https://newsite.it.umich.edu/ as an example site that follows certain assumptions that make the setup much easier.

Contents

Example Site Assumptions

https://newsite.it.umich.edu/

  • Is a subdomain of umich.edu.
  • Is already setup for SSL on the standard port 443.
  • Uses an InCommon certificate from WASUP.
  • The Common Name on the certificate matches our site (wildcard certificates require an exception).

This configuration allows you to use the default policy for Weblogin. Other setups, such as a non-umich.edu domain, can work, but you need to contact the ITS Service Center to request an exception.

Download and Install Cosign

The original Cosign site is no longer maintained. ITS recommends downloading the latest version from the IAM Github.

From the unzipped folder, run these commands as an Administrator:

copy /Y x64\CosignModule.dll C:\Windows\System32\inetsrv
copy /Y x64\Cosign_Schema.xml C:\Windows\System32\inetsrv\config\schema

md "C:\inetpub\temp\Cosign Cookie DB"
cacls "C:\inetpub\temp\Cosign Cookie DB" /E /P BUILTIN\IIS_IUSRS:F

cd %windir%\system32\inetsrv
appcmd install module /name:"Cosign" /image:"CosignModule.dll" /add:"false"
appcmd add module /name:"Cosign" /app.name:"Default Web Site/"

 

Modify C:\windows\system32\inetsrv\config\applicationHost.config

  • Modify C:\windows\system32\inetsrv\config\applicationHost.config, adding the bolded text below.
  • Adjust the four references to the Weblogin host and two references to your site's name.
  • XML is picky about syntax, so be sure to backup this file before changing it. 
<?xml version="1.0" encoding="UTF-8"?>
[...]

<configuration>
[...]

    <configSections>
        <sectionGroup name="system.applicationHost">
            <section name="applicationPools" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="configHistory" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="customMetadata" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="listenerAdapters" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="log" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="serviceAutoStartProviders" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="sites" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
            <section name="webLimits" allowDefinition="AppHostOnly" overrideModeDefault="Deny" />
        </sectionGroup>

        <sectionGroup name="system.webServer">
            <section name="cosign" overrideModeDefault="Allow" />
            <section name="asp" overrideModeDefault="Deny" />
            <section name="caching" overrideModeDefault="Allow" />
            <section name="cgi" overrideModeDefault="Deny" />
[...]
    <system.webServer>
        <cosign>
          <webloginServer name="weblogin-test.itcs.umich.edu" loginUrl="https://weblogin-test.itcs.umich.edu/?" port="6663" postErrorRedirectUrl="https://weblogin-test.itcs.umich.edu/post_error.html" />
          <crypto certificateCommonName="newsite.it.umich.edu" />
          <cookieDb directory="%systemDrive%\inetpub\temp\Cosign Cookie DB\" expireTime="120" />
          <validation validReference="^https?:\/\/.*\.umich\.edu(\/.*)?" errorRedirectUrl="https://weblogin-test.itcs.umich.edu/cosign/validation_error.html" />
          <cookies secure="true" httpOnly="true" />
          <service name="newsite.it" />
          <protected status="off" />
        </cosign>

        <asp />

        <caching enabled="true" enableKernelCache="true">
        </caching>

SSL Certificate Setup

The Weblogin back channel uses mutual authentication, which means it will present a certificate chain to your server, but your server must also present a certificate chain in return. IIS modules do not normally have access to certificate private keys, so you must add permission for the Cosign module.

  1. Run mmc to open a blank Management Console.
  2. Select File > Add/Remove Snap-in... (Ctrl+M).
  3. In the Add or Remove Snap-ins box:
    1. From the list of Available snap-ins, select Certificates.
    2. Click Add.
    3. In the dialog box that pops up:
      1. Select Certificates (Local Computer).
      2. Click Next.
      3. Select Local Computer.
      4. Click OK.
    4. This should add Certificates (Local Computer) to the the Selected snap-ins list.
    5. Click OK.

    Add or Remove Snap-ins page

  4. From the Management Console, expand Certificates (Local Computer) > Personal > Certificates.
  5. Right-click on the site's SSL certificate and select All Tasks > Manage Private Keys.
  6. In the Security dialog box that pops up:
    1. Select the local computer's IIS_IUSRS.
    2. Click Add.
    3. Grant IIS_IUSRS Full control.
    4. Click OK.

    Security dialog box

Enable Cosign On Your Site

The bolded text below must be included, since Weblogin delivers authenticated users to /cosign/valid. The rest of the example demonstrates how to protect specific areas or the site as a whole.

web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- It's VERY IMPORTANT that cosign/valid is excluded from Cosign protection -->
    <location path="cosign/valid">
      <system.webServer>
        <cosign>
          <protected status="off" />
        </cosign>
      </system.webServer>
    </location>

    <!-- A simple example of Cosign-protecting an area -->
    <location path="test/simple">
      <system.webServer>
        <cosign>
          <protected status="on" />
        </cosign>
      </system.webServer>
    </location>

    <!-- This example requires two-factor (Duo) -->
    <location path="test/mfa">
      <system.webServer>
        <cosign>
          <protected status="on" />
          <service>
            <add factor="two-factor" />
          </service>
        </cosign>
      </system.webServer>
    </location>

    <system.webServer>
                <!-- The system.webServer cosign section is the site default -->
        <cosign>
            <protected status="off" />
        </cosign>

        <handlers>
           <!-- Configure CosignModule.dll to handle /cosign/valid -->
           <add name="Cosign Validation" path="/cosign/valid*" verb="*" modules="Cosign" resourceType="Unspecified" />
        </handlers>
        <modules>
            <add name="Cosign" />
        </modules>

    </system.webServer>

</configuration>

Multiple Sites On One Server

The IIS module only supports one certificate per server, so any additional sites on the same server will definitely require a ticket to create an exception. The additional sites can specify a service name within their web.config files:

    <location path="test/simple">
      <system.webServer>
        <cosign>
          <protected status="on" />
          <service name="othersite.it" />
        </cosign>
      </system.webServer>
    </location>
Tags: 
Last Updated: 
Tuesday, April 18, 2017