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 iis7_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.
New Version in V3 of the SP
As of V3, a new IIS plugin is available which provides a richer and more secure integration with IIS version 7 and later. New Installations should use this version unless they are constrained to use IIS version 6 or earlier.
The old DLL plugin (isapi_shib.dll) is still shipped and existing installations will be updated to the latest version of the older DLL.
The configuration for the new plugin is backwards compatible with the old (although it uses Server variables rather than HTTP headers for AttributeAccess by default).
The new DLL takes full advantage of the breadth of the IIS7 APIs. Two notable advantages are:
- By default, it passes values to application using Server Variables rather than HTTP Headers
- It can be easily configured to support native Roles-based Authorization where the roles are derived directly from attribute passed to the SP. An example use of roles based authorization is URL Authorizaion.
Additionally the new plugin allows form-preservation across a SSO login by setting the
postData attribute in the
Upgrading an existing installation
Details on upgrading an installation of the old IIS plugin to the new plugin are given here.
For new installations, refer to the rest of this page.
Installing the Plugin
If the Installer detects IIS7 or later, then the iis7_shib.dll plugin is used. This automatically configures the IIS7 DLL, adding support for both 32-bit and 64-bit app pools.
No need for 32-bit shibd on 64-bit OS
The 32-bit web server modules can function with a 64-bit shibd service, so there is no need to install a special version of shibd to handle 32-bit cases as with older SP versions.
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.
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.
IIS has a design difference that separates it from Apache: it provides no mechanism to securely establish the "canonical" properties of a web site such as its virtual hostname or port. Instead it divides the web server into "site instances" that can have properties like names and ports attached to them (with no reliable/secure way for applications to obtain them). The SP's 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. Note that the hostname" can be inferred by the plugin, but it is usual not to, and can create security vulnerabilities.
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, or handling requests improperly. 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 since IIS has no accessible format for configuring settings like Apache does.
Displaying Server Variable and HTTP Headers
The following file, saved with extension
.aspx will display the information an application can see.
If you are using HTTP headers (which is not recommended) Remember that allowing end users to see the HTTP headers en masse will compromise the spoofing checks because it exposes the random value used to detect manipulation (it's like a secret password).
The IIS plugin has limited support for Roles Based Authorization. This is performed by adding
<Roles> elements to the
<ISAPI> element. However it is currently more usual to either perform the authorization within your application, or rely on the
<RequestMapper> and the XML-based Access Control plugin (or an alternative plugin to the SP).
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.
The new ISAPI plugin cannot be configured alongside the old one. To that aim these two plugins attempt to check against the other using a "signatue check" (to
HKEY_LOCAL_MACHINE\SOFTWARE\Shibboleth\PublicRWKey\IsapiPlugin . As always the issue of differing IIS versions and the ACLs needed can interfere with this test. Although it does not report false positives ("Shibboleth ISAPI filter: ISAPI Filter is already running, exiting" can always be trusted), there are cases when the check cannot proceed. This will yield a warning in the log "Shibboleth Native filter: Failed when looking for signature", Absent another other misfunction, this can be ignored.