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 SP version 3 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..
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 configures 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 post-preservation over a login by setting the
postData= attribute in the
Upgrading an existing installation
Details on upgrading a new installation are given here.
For new installations the rest of this page is relevant.
Installing the Plugin
If the Installer detects IIS7 or later then the iis7_shib.dll plugin is automatically installed. This automatically configures the IIS7 DLL into IIS adding dlls for both 32 bit and 64 bit pools.
No need 32 bit shibd on 64 bit machines.
A 32 bit DLL can function with a 64 bit shibd and so there is no need to install a special version of shibd to handle 32 bit pools.
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 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. Note that the "site name" can be inferred by the plugin, but it usual not to.
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.
Displaying Server Variable and HTTP Headers
The following file, saved with extension
.aspx will display the information.
If you are using HTTP headers (which is not recommended) Remember that allowing users to see the HTTP headers will compromise the spoofing checks.
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.