Page tree
Skip to end of metadata
Go to start of metadata

Overview

These are instructions for installing the Shibboleth SP on the IIS web server. They should work with both IIS 6 and IIS 7, but we recommend using IIS 7 if possible.

Don't Use RadCompression

RadCompression is a popular IIS module that automatically compresses responses before they are sent to the client. It is not compatible with Shibboleth, so you must disable it if you wish to continue. If you don't, you will see a generic 500 error page in your browser and "isapi_shib_extension: Error reading request body from browser (2746)." in your native.log file.

Add Modules (IIS 7+ Only)

By default, IIS 7 does not support the ISAPI filter technology that Shibboleth uses. To use Shibboleth on IIS 7, you must manually enable this support.

  • Go to Start > All Programs > Accessories
  • Right-click Command Prompt and select Run as Administrator
  • Enter these commands one at a time, pressing enter after each one:
dism /online /enable-feature /featurename:IIS-IIS6ManagementCompatibility
dism /online /enable-feature /featurename:IIS-ISAPIFilter
dism /online /enable-feature /featurename:IIS-ISAPIExtensions

If the second "dism" command (to enable the ISAPIFilter feature) fails, try following the instructions on enabling this feature through the graphical user interface using Microsoft's IIS ISAPI Filter instructions.

Install the Service Provider

Download the installer from the Shibboleth site. For 32 bit Windows, use the win32 installer. For 64 bit Windows, use the win64 installer. To determine which one you need, right-click Computer, select Properties, and look for System type. To install:

  • Run the SP installer
  • You should be prompted to reboot
  • Verify that the Shibboleth filter is configured  - see screenshots. The ISAPI filter and .sso extension should be configured at the web site level (e.g. "Default Web Site"), not at the web server level, or you may get 500 server errors and see the message "Extension mode startup not possible, is the DLL loaded as a filter?" in the server's Application log.
  • For IIS 6 users, verify that the priority is set to high (see screenshots)
  • Verify that .sso file extension is mapped to the Shibboleth ISAPI library (see screenshots)

If the filter is not setup correctly, please refer to the Shibboleth site for detailed instructions on setting up the SP.

 IIS 6IIS 7
ISAPI Filter
.sso Extension

Enable the 32-bit Application Pool

The Shibboleth SP software is available for 64-bit and 32-bit versions of Windows, however, even when the 64-bit version is installed, IIS may produce an error web page (500, internal server error) when attempting to access Shibboleth protected URLs.  We've found that this can often be resolved by enabling the 32-bit application pool in IIS.  There are good instructions on how to do this from this web page.

Configure the Service Provider

Site Identifier

First, you need to find the site ID of your IIS site(s). On IIS 7, you can find this under Advanced Settings for the site in IIS Manager. On IIS 6, go to the Web Sites folder in IIS Manager and look in the right pane for a list of the IDs for all of your sites.

Edit the file C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml. Find the line that begins with "<ISAPI". On the next line, specify your IIS application site ID, and enter your site's domain name, like this:

<ISAPI ...>
  <Site id="1" name="hostname.ucsf.edu"/>

</ISAPI>

If you have multiple sites where you want to use Shibboleth, add a Site element for each one. For example:

<Site id="1" name="hostname.ucsf.edu"/>
<Site id="2" name="anotherhost.ucsf.edu"/>

Protected Paths

Still in shibboleth2.xml, find the section like this:

<RequestMapper type="Native">
  <RequestMap>
    <Host name="...">
      <Path name="..." ... />

    </Host>
  </RequestMap>
</RequestMapper>

Set Host name to be your server's domain name, and Path name to be the path in your application that you want to protect with Shibboleth. For instance, to protect https://hostname.ucsf.edu/shibprotected, you would use:

<RequestMapper type="Native">
  <RequestMap>
    <Host name="hostname.ucsf.edu">
      <Path name="shibprotected" authType="shibboleth" requireSession="true"/>

    </Host>
  </RequestMap>
</RequestMapper>

If you wish to protect multiple directories, add more Path elements under Host with different name attributes. If you wish to protect the entire website, replace the entire "<Host>...</Host>" section with the following, substituting your own domain name for hostname.ucsf.edu:

<Host name="hostname.ucsf.edu" authType="shibboleth" requireSession="true" />

If you have multiple sites you wish to protect, use multiple Host elements under RequestMap. Remember that you must also have multiple Site elements defined elsewhere in the file - see the Site identifier section, above.

For example, here is a somewhat complex RequestMapper section covering two sites. The first, somesite.ucsf.edu, has all content protected by Shibboleth. The second, anothersite.ucsf.edu, has the /myapp/ and /anotherapp/ directories protected.

<RequestMapper type="Native">
  <RequestMap>
    <Host name="somesite.ucsf.edu" authType="shibboleth" requireSession="true"/>
    <Host name="anothersite.ucsf.edu">
      <Path name="myapp" authType="shibboleth" requireSession="true"/>
      <Path name="anotherapp" authType="shibboleth" requireSession="true"/>
    </Host>
  </RequestMap>
</RequestMapper>

Generic Configuration

The rest of the changes to shibboleth2.xml aren't specific to IIS. Please follow the generic instructions and return here when you are finished.

Restart the Service

Go to Services under Administrative Tools, and restart the Shibboleth 2 Daemon service.

  • No labels