Page Comparison

Specifies a mapping from IIS site instance ID to logical, normalized request details. If not present the information is garnered from IIS as noted below.

This element is frequently used to allow virtualizing the portThe <Site> element provides a piece of functionality missing from IIS, namely the ability to obtain canonical scheme, host, and port information about an incoming request without just relying on the HTTP request. In addition to being untrustworthy, the client request also contains physical details about the request, which may be completely different from the logical details, which is an issue any time virtualization is involved.

Note

If you’re getting 404 errors trying to access handlers on a site, one common cause is screwing up this element, particularly adding settings you don’t need. Unless you’re virtualizing a site, the only attributes that should be present are id and name. Setting port or sslport (and doing it incorrectly) can cause the system to misinterpret the request and actually NOT intervene to handle it.

As an example, consider a proxy or load balancer that runs at "https://service.example.org", and that sits in front of a pair of IIS servers running on port 8080 without TLS enabled. The actual HTTP request to one of those servers might represent the URL "http://ws1prod.example.org:8080"

If the SP relies on IIS to tell it what to do (which is what applications should do), it will produce redirects or reference itself in SAML messages using the latter URL, and not the former. That's broken. This is why IIS does not support this use case and why you shouldn't use it that way. Apache supports this. Use Apache.

Having said that, if you want a partial solution that supports broken applications running on a broken web server, you can work around the issue by manipulating the content of a <Site> element that corresponds to the IIS web site in use using settings like the following:

Code Block
<Site id="1" scheme="https" name="service.example.org" port="443" />

As with all scenarios involving this feature, the content there is the logical data, not the physical. It will be the same on every server operating behind such a load balancer.

For a similar case where the back-end URLs are TLS-enabled on port 8443, you would need to replace the port attribute in that example and use sslport="443" instead. This allows a single system to be physically hosting both TLS and non-TLS virtualized sites at the same time, so the port is virtualized based on whether the physical request uses TLS or not.

Attributes

The following attributes are availablesupported:

Name	Type	Req?	Default	Description

Populated from if no appropriate <Site>

id

string

required

Y

The IIS instance ID of the web site to protect.

Listed in the IIS web site summary on newer versions,N/A

Newer IIS versions actually display this value in the administration tool.
name	string

required

Y

Canonical logical hostname

of

for the web site

.

The lowercase of the IIS site name

port

integer

80

Logical port for requests

to a non-SSL physical portThe port used to approach the webserver (for non SSL connections)

if the physical request does not include TLS. Do NOT set this attribute unless you are virtualizing.
sslport	integer	443	Logical port for requests if the physical request includes TLS. Do NOT set this attribute unless you are virtualizing.
scheme	string	http

(non secure)
https (secure)

Logical scheme of the web site (typically set to "https" when SSL acceleration is involved)

N/Asslportinteger443

Logical port for requests to an SSL-enabled physical port.

The port used to approach the webserver (for SSL connections)useVariablesbooleantrue

or https	Logical scheme for requests, the default depending on the physical use or non-use of TLS. Do NOT set this attribute unless you are virtualizing.
useVariables	boolean		value from <ISAPI> element	Controls whether attributes are passed

the

to the application as Server Variables

.The default in the containing <ISAPI> element


useHeaders	boolean

false

value from <ISAPI> element

Controls whether attributes are passed 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.The default in the containing <ISAPI> element

ISAPI extension.

Child Elements

Element	Cardinalty	Description
<Alias>	0 more	Rarely-used child element that allows a web site to be accessed

by

via alternate

names

canonical URLs without causing redirects to rewrite the hostname into the primary name. This requires that you duplicate any

request map settings

RequestMapper settings for each

host

combination of URL attributes you want to allow.

Versions Compared

Old Version 4

New Version Current

Key

Attributes

Child Elements