XMLRequestMapper

Overview

Identified by type="XML", this RequestMapper provides a portable XML syntax for configuring settings based on URL host, path, and query string information. It does not permit settings to be defined in the web server's configuration and will not honor them if they're present.

Generally this type isn't used directly, but rather the Native type is used instead, because it layers itself on top of this one, and allows the "right" thing to happen on any given web server. When using IIS, they are functionally equivalent.

When using Apache, the only reason for using this plugin type in favor of the Native type would be to prevent developers with access to content from using .htaccess commands. Since Apache itself can prevent this already, it's largely superfluous, but there could be very small efficiency gains from using it in such cases.

This request mapper's configuration is implemented as a reloadable XML resource, which means that the XML content can be supplied inline, in a local file, or a remote file, and can be monitored for changes and reloaded on the fly. The root of the XML in any of those cases MUST be a <RequestMap> element, either as a child element in an existing file or the root of a different file.

Note that the actual settings that the RequestMapper supports aren't documented here because they don't show up in this element, but rather the <RequestMap> element and its various children.

Reference

Attributes

Aside from the type="XML" attribute itself, there is no other attribute content specific to this plugin type.

It supports all of the attributes common to all reloadable configuration resources:

Names	Type	Default	Description
id	string		Identifies the component for logging purposes.
url	URL		Remote location of an XML resource containing the required configuration. The SP does not verify the transport (i.e. it does not verify the X.509 certificate presented by the remote server when HTTPS is the transport).
path	local path		Path to a local file containing the required configuration
validate	boolean	false	If true, XML validation is performed when loading the resource
reloadChanges	boolean	true	If a path attribute is used, the local file is monitored for changes and reloaded dynamically. This incurs some runtime overhead for locking, so should be disabled if not needed.
maxRefreshDelay	time in seconds	0	If a url attribute is used, this attribute sets the time between attempts to download a fresh copy of the resource. If 0 (the default), no reloading occurs. This incurs some runtime overhead for locking, so should be left at 0 if not needed
reloadInterval			Synonym for maxRefreshDelay
backingFilePath	local path		If a url attribute is used, the downloaded resource is copied to this location. If the software is started and the remote resource is unavailable or invalid, the backing file is loaded instead
certificate	local path		Path to a certificate containing a public key to use to require and verify an XML signature over the resource. The certificate's other content is ignored.
signerName	string		If present, the name is supplied to the <TrustEngine> used to verify an XML signature over the resource. A certificate containing the name must be available in the verification process (typically inside the signature).

Child Elements

The following child element must be provided, either inline (the most common way), or as the root element of a local or remote XML resource to load from, which would be specified via the attribute(s) above.

Name	Cardinality	Description
`<RequestMap>`	1	Root element of configuration

When a non-inline configuration is used, it supports the following child elements common to all reloadable configuration resources.

These child elements are typically only used when relying on a remote configuration resource and are for advanced use cases.

Name

Cardinality

Description

0 or 1

Used to require the presence of a top-level signature over the entire resource and to control the verification process

0 or 1

Used to require the presence of a top-level signature over the entire resource and to control the verification process.

Mutually exclusive with the <TrustEngine> element and the certificate attribute.

0 or more

Provides low-level control over the library used to remotely access the resource

Examples

The most common observed pattern is the "inline" case, and the Windows-installed defaults includes something similar to this example (but it specifies the type as Native instead, as noted above, simply to allow for a Windows install to be easily plugged into Apache. As you can see, there are no bits of content in the root element apart from the type, and the rest is devolved to the required root element, the <RequestMap>, which is documented separately.

Inline Example

<RequestMapper type="XML">
    <RequestMap>
        <Host name="sp.example.org">
            <Path name="secure" authType="shibboleth" requireSession="true"/>
        </Host>
        <!-- Example of a second vhost mapped to a different applicationId. -->
        <!--
        <Host name="admin.example.org" applicationId="admin" authType="shibboleth" requireSession="true"/>
        -->
    </RequestMap>
</RequestMapper>

Alternatively, here's an example of moving the RequestMapper configuration into a separate file, and it is equivalent to the XML above in terms of the RequestMapper behavior.

Pointer to External FIle in shibboleth2.xml

<RequestMapper type="XML" path="request-mapper.xml" />

request-mapper.xml

<RequestMapper xmlns="urn:mace:shibboleth:3.0:native:sp:config">
    <Host name="sp.example.org">
        <Path name="secure" authType="shibboleth" requireSession="true"/>
    </Host>
    <!-- Example of a second vhost mapped to a different applicationId. -->
    <!--
    <Host name="admin.example.org" applicationId="admin" authType="shibboleth" requireSession="true"/>
    -->
</RequestMap>

Note that you can essentially transplant the content from the inline case directly, but you do need to take care of the XML namespace declaration to do so.