The <ISAPI> element provides a piece of functionality missing from IIS, namely the ability to obtain canonical scheme, host, and port information about an incoming request.

This is essential for enforcing request-specific access policy from outside the IIS core engine (which filters like Shibboleth's have to do). It's also necessary to enable proper generation of redirects when running virtualized servers on internal ports.

Apache handles this with the ServerName and UseCanonicalName commands, and Sun/iPlanet servers have an extensible configuration file, but IIS is broken and does not support this capability. IIS will only report scheme, host, and port values based on what the client supplies in its request. This is impossible to trust and cannot be used to look up settings.

<ISAPI normalizeRequest="true">
    <Site id="1" name="www.example.org">
        <Alias>web.example.org</Alias>
    </Site>
    <Site id="1534573457" scheme="https" name="virtual.example.org" port="443">
</ISAPI>

The first element defines a default IIS web site with an Instance ID of "1" that runs on the standard ports. It also authorizes clients to access the site with an alias, and allows the alias to be used when redirects are generated. Using an alias requires that you duplicate any request map settings for each host you want to allow.

Note that content rules specified for the primary hostname will NOT apply when requests with the alias are made. You need separate rules for each alias you want to permit.

The second element is a virtual web site running behind an SSL accelerator that translates SSL requests to non-SSL requests. The scheme and port attributes override the physical settings with logical values seen by the client.

Attributes

• normalizeRequest(boolean) (defaults to true)
  • Equivalent to Apache's UseCanonicalName option, it determines whether the client's request determines the "effective" scheme, hostname, and port of the request, or whether the enclosing <ISAPI> element's mappings do. Should be left true in most cases or security holes can result.

• safeHeaderNames (boolean) (defaults to false) (Version 2.2 and Above)
  • Causes all non-alphanumeric characters to be automatically removed from the names of all SP-controlled headers.

Child Elements

• <Site>
  • Specifies a mapping from IIS site instance ID to logical, normalized request details. Every web site protected by the Shibboleth ISAPI filter MUSTbe listed or the filter will ignore requests to that web site.
    • id(string)
      • The IIS instance ID of the web site to protect. Listed in the IIS web site summary on newer versions, can be dumped by an ASP script on older versions.
    • name(string)
      • Canonical hostname of the web site.
    • scheme(string)
      • Logical scheme of the web site (typically set to "https" when SSL acceleration is involved)
    • port(integer)
      • Logical port for requests to a non-SSL physical port.
    • sslport(integer)
      • Logical port for requests to an SSL-enabled physical port.
    • <Alias>
      • Rarely-used child element that allows a web site to be accessed by alternate names without causing redirects to rewrite the hostname into the primary name. This requires that you duplicate any request map settings for each host you want to allow.