Page tree

The Shibboleth 2.x software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP30 and SP3 wiki spaces for current documentation on the supported versions.

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

Version 1 Next »

The SP software includes an implementation of the RequestMapper plugin interface that combines "native" configuration support specific to certain web servers with a portable mechanism that relies on an XML syntax for applying settings to content and works across all the supported platforms.

A more complete syntax reference to using this mechanism can be found in the NativeSPRequestMap topic. This topic will outline how to use it, show some examples, and note some potential mistakes.

Apache Use

If you're using Apache, you should consider using the native ShibRequestSetting command, as it's generally safer and more natural to use. If you want to use the XML syntax instead, be sure to turn on the UseCanonicalName Apache option to avoid leaving security holes.

General Structure

The XML-based syntax operates against the logical URL requested by the client, and not the physical path or file accessed. This is analagous to the difference between the Apache <Location> and <Directory>/<Files> distinction.

The mapper executes by breaking apart the requested URL into three parts: the host, path, and query. Each portion is then matched against the elements inside the <RequestMap> in order to locate the "deepest" matching element, which is then used to derive the content settings to apply to the request.

The structure of the map, as with XML in general, is of a tree, with elements nested inside of other elements in a parent child relationship. The mapping process walks this tree by evaluating each set of siblings and, when a match is found, descending into the matching element to evaluate its child elements, and so on. The information from the requested URL that matches is "consumed" each time the algorithm descends into a matching element, and only the remaning portion, if any, is available for further matching. Eventually, nothing is left to match against, no child elements remain, or none of them match. At that point, the process stops with the last matched element and it forms the bottom of the tree to use.

To see how this works in practice, consider this moderately complex example. No actual content settings are shown, as would be found in a real example, to emphasize the matching process.

<RequestMap>   <!-- A -->
    <Host name="sp.example.org">   <!-- B -->
        <Path name="secure"/>      <!-- C -->
        <Path name="admin">        <!-- D -->
            <Path name="secure"/>  <!-- E -->
        </Path>
        <Path name="admin/badexample"/>  <!-- Do NOT do this, it will be ignored! -->
        <Path name="combined/path"/>  <!-- F -->
    </Host>
    <Host scheme="https" name="internal.example.org"/>   <!-- G -->
</RequestMap>

Assuming that the web server is appropriately configured, the table below shows which element (labeled in the XML comments above as A-G) each input URL will map to.

Request URL

Maps to...

Notes

https://internal.example.org/anything

G

 

http://internal.example.org/anything

A

the scheme is http, not https.

http://sp.example.org/stuff

B

the path portion doesn't match

https://sp.example.org/secure/anything

C

 

https://sp.example.org/admin/stuff

D

 

https://sp.example.org/admin/secure/anything

E

 

https://sp.example.org/combined/stuff

B

the path portion doesn't match

https://sp.example.org/combined/path/anything

F

 

Overlapping Siblings

In addition to the examples, note the comment above warning about the "admin/badexample" element. This is the most common mistake made and is an example of "overlapping siblings". The bad element contains a pathname that overlaps in the URL tree with an earlier-declared sibling element (D). They are siblings in XML terms, elements with the same immediate parent element (B).

The implementation does not allow siblings to "overlap" in the URL tree, and it will ignore the overlapping element, producing unexpected results.

  • No labels