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.
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 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 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.
handlerURL
(a relative or absolute URL) (default is "/Shibboleth.sso" on 2.4+, required otherwise)<Sessions>
element.handlerSSL
(boolean) (defaults to true)lifetime
(time in seconds) (default is 28800)seconds
that a session maintained by the SP will be valid. The actual time may be less than this value (if an IdP indicates it should be shorter) but will never be longer. Note that this will not influence sessions maintained by an application.timeout
(time in seconds) (default is 3600)maxTimeSinceAuthn
(time in seconds)ForceAuthn
flag was honored.checkAddress
(boolean) (default is true)consistentAddress
(boolean) (default is true)checkAddress
setting to block legitimate access.cookieName
(string)cookieProps
(string) (default is "; path=/; HttpOnly"
)path
or the secure
and HttpOnly
flags to the cookies. A common value for SSL-only use is "; path=/; secure; HttpOnly"
. As of V2.5, this property can be set to a pair of built-in values, "http"
and "https"
, which expand to the default and SSL-only properties respectively.idpHistory
(boolean) (default is false)idpHistoryDays
(time in days)exportLocation
(an absolute or relative URL)Location
attribute. Note that using an absolute hostname like "localhost" results in an application-specific location that can't be inherited by ApplicationOverride
elements. You'll need to supply a custom <Sessions>
element with its own value for this attribute as well as all the other usual settings.exportACL
(space-delimited list of IP addresses) (default is 127.0.0.1)Version 2.1 and Above:
cookieLifetime
(time in seconds)Version 2.2 and Above:
postData
(string)postTemplate
(path to file)postLimit
(number of bytes)postExpire
(boolean) (default is true)Version 2.4 and Above:
relayState
(string)<StorageService>
element, typically "ss:mem". As of V2.5, the "cookie" option can include a ":n" suffix, where n specifies the number of cookies to permit before purging old ones, defaulting to 25.Version 2.5 and Above:
redirectLimit
(see below for allowable values) (default is "none")redirectWhitelist
setting.idpHistoryProps
(string) (defaults to "; path=/;")cookieProps
setting for the SAML "discovery" cookie enabled by the idpHistory
flag. Primarily this is useful if there's a need for the discovery cookie to be accessible to client side scripts (while leaving the HttpOnly
property enabled for other cookies).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:
<SSO>
(zero or one) (Version 2.4 and Above)<Logout>
(zero or one) (Version 2.4 and Above)<NameIDMgmt>
(zero or one) (Version 2.4 and Above)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.
<SessionInitiator>
<SSO>
service element.<LogoutInitiator>
<Logout>
service element.<md:AssertionConsumerService>
<SSO>
service element.<md:ArtifactResolutionService>
<md:SingleLogoutService>
<Logout>
service element.<md:ManageNameIDService>
<NameIDMgmt>
service element.<Handler>