NativeSPIIS7Config

Introduction

The IISNative DLL is an Shibboleth integration against the API set which was introduced in IIS7.  The previous version (isapi_shib.dll) integrated against the old "ISAPI" APIS which in turn required the deployment of explicit down-level support dlls to provide interfaces to the legacy API.  The new DLL is a functional super set of isapi_shib plugin, but it does not automatically replace the old one (which is still shipped).

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.

Configuration

The new plugin is configured using an extension to the existing NativeSPISAPI element (and this documentation will move there).  The following changes should be noted

• If a <Site> element is not specified for a site which uses the plugin then the configuration is taken from IIS.  Notably the host name is derived from the lower case of the name given to the site.
• If a <Site> element is specified the following extra attributes can be provided:
  • useVariables=boolean (default true) controls whether attributes are passed the the application as Server Variables.
  • useHeaders=boolean (default false)  controls whether attributes are passed the the application as HTTP Headers.  This setting should be avoided, but is present to provide a level of compatibility with applications developed against the old isapi_shib plugin.
• Additionally, a new element <Roles> may be specified.  This configures the roles that can be used in native Roles-based Authorization.  The following elements can be provided:
  • authNRole=string (default ShibbolethAuthN).  Any principal which is logged in via the Shibboleth SP is given this role.
  • roleAttributes=space-separated-string-list (no default).  All values of all provided attributes with the names given are added to the Roles associated with this principal

<ISAPI normalizeRequest="true" safeHeaderNames="true">
    <Roles roleAttributes="ePa ePsa" />
	<Site id="1" name="iis.example.org"/>
</ISAPI>

The first site will be given the host name iis.example.org.

Every SP-authenticated principal will be given the role ShibUser.  Additionally the attributes 'ePa' and 'ePsa' will be queried and their values used as roles.  Hence if a user logged in via the SP and the following attributes were provided

• eppn :  "User"
• ePa : "member", "walkin"
• epSa: "staff@example.org", "member@example.org"

The session would be have the REMOTE_USER variable set to be "User" (assuming that the default setting for ApplicationDefault> were used. and the following roles

• ShibbolethAuthN  (by Virtue of being "logged in")

• member

• walkin

• staff@example.org
  

• member@example.org

Installation

The installation is available here

For the test release the IIS7Native plugin is installed on top of an existing Shibboleth SP installation.  It is expected (but not required) that the installation would have the old style ISAPI plugin configured.  You may need/wish to stop IIS during the installation. The installation runs with no dialog and does the following

• Updates the schema definition for shibboleth2.xml to include the new definitions
• Updates the ISAPI plugin to include code to test for dual (mis) configuration
• Installs the new Native plugin DLL
• Configures the IIS with the new plugin.

The installation does not deconfigure the old plugin and you need to do this by hand. Doing this is highly installation dependant (which is why there is no automation) but the following hints may help

• In the GUI, select the server in the left hand pane and click on the "ISAPI Filters" in the right.
  • Now remove any Shibboleth related filters.  For a default install this will be called Shibboleth and be for executable C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll
• In the GUI, select the server in the left hand pane and click on the "Handler Mappings" in the Right.  
  • Now remove any Shibboleth related ISAPI handler.  For a default install this will be called something like AboMapperCustom-8689 and be for executable C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll

• In the GUI, select the server in the left hand pane and click on the "ISAPI and CGI Restrictions" in the Right.  

  • Now remove any Shibboleth related restriction.  For a default install this will be called something like Shibboleth Web Service Extension and be for executable C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll

• Edit %SYSTEMROOT%\System32\InetSrv\config\applicationHost.config and look for the words "shib" or "shib_isapi".  The following is the new definition

  <globalModules>
    ...
    <add name="ShibNative" image="C:\opt\shibboleth-sp\lib64\shibboleth\iis7_shib.dll" />
  </globalModules>
  ...
  <modules>
    ...
    <add name="ShibNative" />
  </modules>

  and should be left along.
  
  In particular the string isapi_shib.dll indicates that the removal is incomplete.  Such entries should be removed,

• As well as the applicationHost.config file, you may need to inspect the web.config files for the sites and their sub folders.

If the ISAPI module is still configured the following tell-tales will indicate it

1. The event viewer ("Windows Logs\Application") may show a warning from SHIB_ISAPI

2. An attempt to access a protected resource will return a failure (status 500) and the native log will have the following line

   ERROR Shibboleth.NATIVE [<pid>] native_shib: Shibboleth handler invoked at an unconfigured location.

   This indicates that configuration for the ISAPI filter is still active somewhere.