Sessions

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, virtually none of its individual XML attribute properties will be inherited from the default element. You must supply almost 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. See Inheritance Rules for more details.

Please take note of the redirectLimit setting and your current posture. For compatibility reasons, the underlying default for this setting remains “none”, which allows the SP to be manipulated into serving as an open redirector.

The project’s position is that this is not a security issue, just a suboptimal default that will be changed in a future major update to the software. As of several releases ago, the shipping default explicitly sets this to “exact” instead (which will be the underlying default in the future), and we encourage deployers to ensure that the setting matches their intended posture.

1 Attributes
2 Simplified Protocol Configuration
- 2.1 Child Elements
3 Advanced Configuration

Attributes

Name	Type	Default	Description

Name	Type	Default	Description
handlerURL	URL (relative/absolute)	/Shibboleth.sso	The base location on the server that dispatches requests to the handlers configured inside the <Sessions> element.
handlerSSL	boolean	true	When true, only web requests over SSL/TLS will be processed by handlers. Other requests may be blocked, or possibly ignored (and usually result in a 404 error) depending on the web server, but will never be processed. This is useful for sites that want to protect SAML protocol traffic but leave actual content unencrypted.
lifetime	seconds	28800 (8 hours)	Maximum duration in 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	seconds	3600 (1 hour)	Maximum inactivity allowed between requests in a session maintained by the SP. This inactivity applies only to requests to this SP and is not aware of activity between the browser and other web sites (or even other applications on this system). A value of 0 disables timeout checking, but the expiration of the session may be otherwise bounded by the cacheAllowance setting on the SessionCache.
maxTimeSinceAuthn	seconds		If set, the SP rejects assertions that indicate the user's actual time of authentication to the IdP is older than the difference between the current time and this value. Essentially this limits the amount of time between the act of authentication and the attempt to access the SP. This can be useful to ensure that the SAML 2.0 ForceAuthn flag was honored.
checkAddress	boolean	true	The IdP will place the IP address of the user agent it authenticated into the assertions it issues. When true, the SP will check this address against the address of the client presenting an assertion before creating a session. While useful for security, NAT and proxy usage (as well as IPv6 support on only either the webserver hosting the IdP or the SP) often make this setting a source of errors.
consistentAddress	boolean	true	When true, the SP will remember the IP address used when creating a session and ensure that all subsequent access associated with this session come from the same address. This can help protect against cookie theft and is less likely than the checkAddress setting to block legitimate access.
cookieName	string		Rarely needed, this can be used to override part of the names used for cookies maintained by the SP. The name is used in combination with other values that are part of the SP implementation and not documented. It is not meant to allow full control over the name but can be useful in some scenarios in which virtual server domains overlap
cookieProps	string	"; path=/; HttpOnly"	If set to a custom string, the string is appended to the cookie values maintained by the SP. Used to attach custom meta-properties like path or the secure and HttpOnly flags to the cookies. A common value for SSL-only use is "; path=/; secure; HttpOnly". This property can also be set to a pair of built-in values, "http" and "https", which expand to the default and SSL-only properties respectively. Do not include a SameSite attribute, as this is either automatic for most cross-site cases or can be controlled with the sameSiteSession property below.
sameSiteSession^3.1	"None", "Lax", "Strict"		Allows session and session recovery cookies to be assigned a SameSite attribute. Omitting this setting results in behavior that will depend on the browser. Note that "Strict" is provided for completeness but will generally be non-functional because of when these cookies are set.
sameSiteFallback^3.1	boolean	false	This enables a workaround for a Safari bug and causes a second cookie to be set in any case that a cookie is being set with a SameSite=None attribute. It should be removed once support for out of date versions is no longer required.
idpHistory	boolean	false	When true, the SP will maintain a SAML "discovery" cookie in the browser by adding any identity provider successfully used to the cookie.
idpHistoryDays	days		Determines how long the history cookie will persist. If not set, the cookie will expire when the browser closes.
exportLocation	URL (relative/absolute)		This is the handler location supporting local lookup of raw SAML assertions cached with a session (see this topic). When absolute, you can override the usual insertion of the hostname and force the use of "localhost". When relative, it expands much like any handler's 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 IP addresses	127.0.0.1	The set of requesters allowed to query the SP for assertions using the mechanism described in the Assertion Export topic. This should almost always be left as "127.0.0.1" (or "::1" for IPv6) to prevent third parties from viewing sensitive data about users. No other security mechanism is currently supported. IPv6 addresses must be provided in the non-dotted format with lower case letters and without padding '0's. E.g. "2001:620:0:40:c62c:3ff:abc:123"
cookieLifetime	seconds		If set, cookies used for session management will be created with the designated lifetime. When omitted, which is the default, such cookies are in-memory only and do not persist across browser restarts (assuming various session restore features aren't in use). Note that this will not affect "transitory" cookies used for maintaining state across redirects.
postData	string		Allows for the preservation of form POST data (with Content-Type application/x-www-form-urlencoded) across SSO on supported platforms and identifies the mechanism for preserving that data. Currently this MUST take the form "ss:<id>" where <id> is the ID of a configured StorageService plugin.
postTemplate	path to file		Path to an HTML template with the markup necessary to carry replayed form POST data and if possible prevent accidental replay if the back button is hit. Refer to the default postTemplate.html file as a guide.
postLimit	number of bytes	1024 * 1024	A maximum number of bytes to allow when saving off POST data. Over this limit, a warning in the log will appear, but the data will not be saved.
postExpire	boolean	true	If set, causes the HTTP response containing to-be-replayed form POST data to be expired and non-cacheable by the server using the usual mix of response headers. Can be adjusted to accommodate varying strategies for back-button/replay prevention.
relayState	string		Controls how information associated with requests for authentication, primarily the original resource accessed, is preserved for the completion of the authentication process. If not specified, the resource URL is passed by value to the IdP, when possible. A value of "cookie" causes the URL to be saved in a cookie, to protect the user's privacy. A third option, which is recommended, is to use the SP's persistent storage by specifying a value of the form "ss:id", where id references a <StorageService> element, typically "ss:mem". The "cookie" option can include a ":n" suffix, where n specifies the number of cookies to permit before purging old ones, defaulting to 25.
redirectLimit	V3.2+: One of "none", "exact", "host", "allow", "exact+allow", "host+allow" Earlier: One of "none", "exact", "host", "whitelist", "exact+whitelist", "host+whitelist"	"none" Recent (3.1+) default configurations as shipped set this to "exact" explicitly	Prevents the injection of redirect locations after login or logout that don't meet specific criteria, to prevent misusing the SP to carry out phishing attacks. "none" is the default and does no limiting ( Consider carefully before using this option as it can allow malicious use of your SP as an open redirect). "exact" requires that the destination match the exact scheme, hostname, and port of the handler performing the redirect. "host" requires that the destination match the hostname of the handler performing the redirect. "allow" / "whitelist" requires that the destination's "scheme://hostname[:port]/" matches an allowed list of whitespace-delimited URL prefixes. Allows explicit permission to send the client off-host to external systems. The list of URL prefixes are set via the redirectAllow (formerly redirectWhitelist) setting. "exact+allow" / "exact+whitelist" combines the "exact" and "allow" policies above, without requiring explicit enumeration of the handler's vhost. "host+allow" / "host+whitelist" combines the "host" and "allow" policies above, without requiring explicit enumeration of the handler's host.
redirectAllow (V3.2+) redirectWhitelist (Older)	whitespace-delimited URL prefixes		One or more whitespace-delimited URL prefixes of the form "scheme://hostname[:port]/". Used with subset of redirectLimit values above. Don't forget the trailing slash because e.g. specifying "https://example.com" also allows example.com.evil.com etc.
idpHistoryProps	string	"; path=/;"	May be used to override the standard 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).

Simplified Protocol Configuration

Virtually all configurations should stick to the simplified syntax for auto-configuring protocol-related handlers 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 but that will create a much higher burden on future maintainers of your configuration so should usually be avoided. If you absolutely have to do it, it's best to replace the new elements entirely to avoid unforeseen overlaps and interactions.

Child Elements

The usual content of the <Sessions> element will be one or more "service" elements, along with an optional set of custom <Handler> elements for more general features.

Name	Cardinality	Description

Name	Cardinality	Description
<SSO>	0 or more	Enables support for one or more Single Sign-On / Authentication protocols
<Logout>	0 or more	Enables support for one or more Logout protocols.
<NameIDMgmt>	0 or more	Enables support for one or more NameID Management protocols. Rarely used.
<Handler>	0 or more	Generic endpoint for non-specific functionality implemented by the SP or an extension library.

Advanced Configuration

The above three elements are shorthand configuration for a more complex mechanism as described below using explicit handlers.

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"). This is strongly discouraged, as it is very hard to configure.

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.

Advanced Configuration by Protocol

The advanced child elements listed below have variants for each protocol type and are documented as such. However deployers are liable to care about a particular protocol.

There is also support for Local-only logout.

Child Elements

The usual content of the <Sessions> element will be one or more "service" elements, along with an optional set of custom <Handler> elements.

Name	Cardinality	Description

Name	Cardinality	Description
<SessionInitiator>	0 or more	Initiates sessions by creating an a request for authentication specific to a particular SSO protocol, or invoking some kind of IdP discovery mechanism. Almost always superseded by the <SSO> element; you should not in general ever need to consider configuring this directly.
<LogoutInitiator>	0 or more	Terminates a session by invoking some kind of logout process, which may be local to the SP or global to the SSO environment. Almost always superseded by the <Logout> element; you should not in general ever need to consider configuring this directly.
<md:AssertionConsumerService>	0 or more	Incoming entry point for messages carrying SAML SSO assertions to initiate a user session. The terminology is borrowed from the SAML spec (as is the actual element). Almost always superseded by the <SSO> element; you should not in general ever need to consider configuring this directly.
<md:ArtifactResolutionService>	0 or more	Incoming SOAP endpoint for the resolution of SAML 2.0 artifacts into protocol messages. This is used when transmitting outbound messages as artifacts by the SP, which is borderline unheard of. (Artifacts issued by an IdP are processed by other endpoints.) The terminology is borrowed from the SAML spec (as is the actual element). Almost always superseded by the various service elements; you should not in general ever need to consider configuring this directly.
<md:SingleLogoutService>	0 or more	Incoming entry point for single logout protocol messages from an IdP (acting in its role as a session authority). The terminology is borrowed from the SAML spec (as is the actual element). Almost always superseded by the <Logout> element; you should not in general ever need to consider configuring this directly.
<md:ManageNameIDService>	0 or more	Incoming entry point for NameID management messages from an IdP. The terminology is borrowed from the SAML spec (as is the actual element). Almost always superseded by the <NameIDMgmt> element; you should not in general ever need to consider configuring this directly.