Installing the Shibboleth SP for IIS 7.x

Known Conflicts

The following software is known to cause incompatibilities that affect the installation or use of the Shibboleth SP module:

• The installer does not work fully in conjunction with the IIS "Shared Configuration" option. Disable it prior to installation. After re-enabling it, you will likely have to manually apply some of the configuration changes noted below.

• Per this report, the "DevExpress HTTP Handler" appears to be incompatible with Shibboleth.

Preparation

IIS7 is a rather radical rewrite and has some major differences from earlier versions. Superficially, the administration GUI is very different. Furthermore, the scripting interfaces used by the SP installer are not supported by default.

If you want the installer to configure IIS for you, you'll need to make sure the IIS6 management compatibility role services are installed first. In the server roles administration tool, IIS includes a set of role services labeled "IIS 6 Management Compatibility". Install these before performing the SP installation.

You also need to ensure that support for ISAPI filters and extensions is installed. This appears to be a separate installable feature in some cases.

Finally, you need to determine whether your IIS applications are expected to be 32-bit or 64-bit. Typically, a newer 64-bit OS will run 64-bit IIS by default, but some applications require 32-bit. For older SP versions, only one copy of the SP can be easily installed, so you'll have to pick one or the other, and install the appropriate version to match the applications you want to run. As of V2.5+, the installation package is limited by your system type, and the 64-bit installer will include both sets of files so you can adjust which type you use on the fly.

Installation

1. Download the appropriate 32- or 64-bit .msi Shibboleth SP installer from the Shibboleth download site.
2. Run the installer. The installer will prompt for an install path, change default configuration files as appropriate for Windows, and set various environment variables for you. The shibd service will also be installed for you.

After rebooting, IIS should be configured for basic support (if you asked it to do so and you installed the IIS 6 compatibility services mentioned above). If you have problems, need to manually configure it, or want to verify what happened, the IIS steps are as follows:

1. Add the filter using the IIS Manager console. At either the top-level or individual Site level, select the "ISAPI Filters" feature; then, add a new filter called Shibboleth and specify the lib\shibboleth\isapi_shib.dll library. For V2.5+ on a 64-bit IIS, the relative path is lib64\shibboleth\isapi_shib.dll
2. Map the *.sso file extension to the ISAPI library so that virtual URLs can be specified to invoke the extension handler for each web site. This is done under "Handler Mappings" using the "Add Script Map..." action. The Executable box should point to isapi_shib.dll, and the "Extension" can be set to anything unlikely to conflict, but *.sso is assumed (and the asterisk and dot must be included).
   
   1. Configure Request Restrictions for the handler mapping to permit the handler to execute for all requests that match the extension. While still in the "Add Script Map" dialog, click on "Request Restrictions." In the "Mapping" Tab, un-check the option labeled, "Invoke handler only if request is mapped to..." If checked, the handler will activate only for real files or folders matching the extension, instead of activating on all requests, regardless of whether the file exists. (After saving the script map, the "Path Type" column for the new handler in the Handler Mappings list should be "Unspecified.")
3. Add the Shibboleth ISAPI Extension to the list of permitted extensions in the list of allowed extensions. This is under "ISAPI and CGI Restrictions" at the top level.
4. Restart IIS. At this point, I don't know enough of IIS7 to know how to diagnose filter load problems, but the filter does log startup and shutdown events in the Windows event log.

A set of commands that may work for some people to perform the above steps:

cd C:\Windows\System32\inetsrv appcmd set config /section:isapiFilters /+[name='shibboleth',path='C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll',enabled='true'] appcmd set config /section:handlers /+[name='Shibboleth',path='*.sso',verb='*',scriptProcessor='C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll'] appcmd set config /section:isapiCgiRestriction /+[path='C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll',description='Shibboleth',allowed='True'] iisreset

For Windows Server 2012 / IIS 8, you may need to add the modules attribute to the Handler Mapping command:

appcmd set config /section:handlers /+[name='Shibboleth',path='*.sso',verb='*',scriptProcessor='C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll',modules='IsapiModule']

Basic Configuration

• IIS7 may require that you manually install the script mapping and/or the filter itself at the site level, rather than at the root of all the sites. You may also wish to do this to ensure that the filter only runs on a subset of your web sites.

• The primary configuration file for the filter and the Shibboleth daemon, shibd, will be located at \etc\shibboleth\shibboleth2.xml (within the directory used to install the SP software).

• shibd creates its own log at \var\log\shibboleth\shibd.log and must have appropriate read and write permissions itself for the entire installation directory.

• If you are trying to use the 32-bit version with 64-bit Windows, and getting 500 errors, you may need to edit the advanced settings for the IIS application pool you're using and enable 32-bit applications in order to load the software. Conversely, using the 64-bit version if 32-bit applications are enabled will also fail.

• IIS may be configured by default to suppress the error responses that the SP returns to the browser and use its own error pages instead. These will be generic looking and include a large indicator of the error status (such as a 500). This can make debugging problems more difficult. You can change this behavior by modifying the Error Pages setting in the IIS administrative GUI. Click "Edit Feature Settings..." on the right hand side and make sure "Detailed errors" is selected.

• You may need to add permissions to your installation directory for IIS to operate. There are a variety of possible accounts IIS may run with at different times, and failure to set permissions may result in crashes, the filter failing to load, or other odd behavior. The IIS server processes need read access to most of the installation, with the exception of your Shibboleth private key file(s). It also needs write access to \var\log\shibboleth to create the native.log file. IIS 7.x appears to rely largely on accounts that live in the "IUSRS" Windows group, so giving that group read access to the installation may be helpful or essential.

• In order to configure Shibboleth you'll need the site identifier that IIS has assigned to your website. If you're simply using the default website this identifier is 1 (one). If you're not you can find the identifier through the IIS Manager tool by selecting the "Web Sites" folder and looking in the identifier column, on the right, that corresponds to your website.