The <Sessions> element broadly speaking controls how the SSO process is managed by the SP. It typically contains a number of child elements called "handlers" that act together to provide the core SAML functionality of the software. It also contains settings that govern how long SSO sessions last and how they're protected from certain kinds of attacks.

Each <ApplicationOverride> inherits the default settings and endpoints defined at the top level, and can contain its own <Sessions> element, if needed, to add additional endpoints. Note that if you supply a <Sessions> element in an override, none of its individual XML attribute properties will be inherited from the default element. You must supply all of them that you want to have non-defaulted values. In contrast, the elements from the parent <Sessions> element do get inherited/used if you don't override them. It's not terribly intuitive, an artifact of the code.

Simplified Protocol Configuration (Version 2.4 and Above)

Version 2.4 introduces a simplified syntax for configuring protocol-related handlers by expressing support in terms of "services" and "protocols". The currently supported services are:

A service is enabled by including the corresponding child element(s). Each service element contains a set of properties to configure the service, and the element's value is a list of protocol names that the SP supports. Each supported service element can appear only once, as this is a simplified approach that is meant to capture all of that function's behavior in a single element. More advanced cases may require reverting to older syntaxes, but this isn't usually necessary and you may want to ask on the support list before reverting to that.

These services and names are used to locate detailed information about the handlers to install based on a <ProtocolProvider> plugin. The implementation supplied with the SP relies on a separate configuration file to spell out the detailed information that used to appear within the <Sessions> element.

You can still plugin all of the older information by hand if you need unusual settings or more control over the internals. It's best to replace the new elements entirely to avoid unforeseen overlaps and interactions.

Handlers and Endpoint Construction

Handlers perform the work of the SP apart from the general request filtering work it performs for all requests. While handlers are essentially just mini-applications that could be built as CGI scripts, they're implemented inside the SP to avoid scripting language dependencies and to provide them with full access to the SP library API.

The SP uses a model in which handlers are dispatched based on "path info" that is appended to a base location that acts as a kind of virtual resource that the web server knows about and asks the SP software to implement. Sometimes this is referred to by the web server as a script mapping or handler.

Because the SP's handlers have to know which application is receiving a request, each application has to be assigned a unique "base location", which is called a handlerURL. By convention, this base location is "/Shibboleth.sso". 

Often, each application spans a particular virtual host, and the base location is simply "/Shibboleth.sso" on that vhost. In more advanced cases, an application might live inside a subset of a virtual host's document tree. In that case, the base location has to be inside that document tree (e.g., "/path/Shibboleth.sso").

Each handler element has a Location XML attribute that, when appended to the base location, provides the full path to the handler. Combining that path with the virtual host's scheme, hostname, and port, you have the full URL of the handler:

http(s):// + hostname + [:port] + handlerURL + Location

If you require to access the handler URL from your code (for example to trigger a login), the "Shib-Handler" attribute is availble set to the full path above (minus the Location) for a programatic way to access the path set in the configuration.

In turn, these endpoint locations are usually supplied to partner sites in Metadata. When they don't match the metadata, various errors will result.


Version 2.1 and Above:

Version 2.2 and Above:

Version 2.4 and Above:

Version 2.5 and Above:

Child Elements

For Version 2.4 and above, the usual content of this element will be one or more "service" elements, along with an optional set of custom <Handler> elements.

The defined service elements, in the order they must appear is:

Prior to Version 2.4, the child elements defined for this element were the various kinds of handlers supported by the SP. A number of different pre-defined elements are used for handlers with particular significance, often lifted directly from the SAML Metadata schema. A generic element is also used for extension handlers with a more varied nature.

Handlers can appear in any order and need not be grouped into like types, although this is useful for clarity. Some handler types are "indexed", which means they carry labels for referencing elsewhere, and can be marked with an isDefault attribute. Order is only significant when determining a "soft" default; that is, if no handler of a particular type is marked as a default, the first one will be used as such.