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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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 <Sessions> element

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.   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.

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.

Configuring

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.

Authorization

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).

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 How To topic.

  • No labels