Page Comparison

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.

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"

Some 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).