The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

NativeSPIISConfig

Owned by Scott Cantor
Last updated: Feb 19, 2010Version comment
2 min read

Half of Shibboleth runs within the web server. For IIS, this half is implemented in an ISAPI filter and extension packaged in a single file called isapi_shib.dll. Because most versions of IIS provide very minimal support for the configuration of extensions on its own, all of the runtime configuration is handled by the SP configuration file (shibboleth2.xml) with the exception of the basic installation of the filter and extension into IIS.

Loading the Filter and Extension

The low-level IIS installation details have been documented as part of the Windows installation process, and can be found linked from the NativeSPWindowsInstall topic for each supported version of IIS.

Typically, environment variables are used to set the appropriate path information to enable the library to locate the configuration file and initialize itself when IIS or its child processes are started.

Startup Failures

If you experience startup problems, you should do the following:

  • Verify the configuration is generally valid by running %SHIBSP_PREFIX%/sbin/shibd.exe -check from the command line.
  • Assuming that reports no serious errors, verify that all of the machine accounts used by IIS have read permission to the SP installation tree.

Enabling the Filter

Populate the <ISAPI> element in shibboleth2.xml with <Site> elements that reflect the IIS site/vhost configuration, and then use the <RequestMapper> to apply content settings.

IIS has a design difference that separates it from Apache: it provides no mechanism to securely establish the "canonical" properties of a web site like it's hostname. Instead it divides the web server into "site instances" that can have properties like names and ports attached to them. The SP's portable internals don't understand the concept of a "site", so to correct for this, a non-portable piece of XML configuration is included within the <ISAPI> element that performs a mapping between a site instance number/ID and the associated "canonical" virtual host information.

It is critical when performing initial setup, and when adding new Shibboleth-enabled web sites to an IIS server, to create those mappings. Failure to do so will result in the system ignoring requests to unmapped sites. Note that this is also a feature: any site instances you provide no mapping for will be ignored by the software.

Any time you manipulate the <ISAPI> configuration section, you'll need to restart IIS completely.

Once the necessary site instance mappings are created, the rest of the per-request configuration is handled exclusively by the <RequestMapper> component. There is no "native" option as with the other web server implementations.

Authorization

The module does not provide for integration with the native access control features of the web server. Therefore you will need to either perform such work within your application, or rely on the <RequestMapper> and the XML-based Access Control plugin (or an alternative plugin to the SP).

Content Settings

The SP supports an extensible set of content settings, properties that control how it interacts with requests and enforces various requirements. On IIS, these settings can be controlled only by attaching properties using the <RequestMapper> mechanism in the SP configuration.

For more information about using the <RequestMapper> feature, refer to the NativeSPRequestMapHowTo topic.