SessionConfiguration

Current File(s): conf/idp.properties

Format: Properties

1 Overview
2 Address Binding
3 Session Timeouts
4 Reference

Overview

An IdP session is created by default (idp.session.enabled=true) upon a successful authentication event. The IdP session uses a sliding window expiration policy that is updated under one of two conditions:

An existing authentication result stored in the session is used to satisfy security demands made by an SP.
A new authentication result is created from a successful user authentication event in order to satisfy security demands made by an SP. The new result is also stored in the session.

Thus the IdP session tracks all authentication events that occur during the lifetime of the session, represented by objects of type AuthenticationResult. When the idp.session.trackSPSessions flag is enabled, the IdP session also tracks successful requests to access SPs, represented by objects of the base interface SPSession; this facility is required to support single logout.

The IdP session stores each AuthenticationResult keyed on the ID of the login flow that handles the authentication process. The consequence of this design is that a subsequent invocation of the same login flow, for example in response to a forced authentication request, would overwrite a previous result of the same flow. Results stored in the IdP session are themselves subject to expiration by a sliding window up to an absolute limit. If an SP makes a request to the IdP and there is no active authentication result that satisfies the security demands of the SP, the user is forced to reauthenticate.

(A deeper dive into the internals of this design can be found in the Sessions topic.)

Address Binding

IdP sessions are by default bound to an "address" in order to prevent trivial session takeover simply through session cookie exposure. This can be disabled via the Idp.session.consistentAddress property or relaxed in arbitrary ways through the idp.session.consistentAddressCondition extension point. It is deeply ill-advised to simply disable this checking entirely and it deeply unsafe to operate networks that hide a plethora of clients behind a single address.

The latter extension point relies on supplying a BiPredicate (a condition that takes two inputs). The first parameter is the address string to which the session is already bound, and the second parameter is the address string that is being tested/evaluated for “equivalence” with the first parameter. That is, the default implementation of this simply compares the two strings for equality.

One existing implementation of this feature is the IPRangeBiPredicate class, which is configured with a number of IPRange objects, and will consider the two input strings “equivalent” if they both fall into one of the supplied ranges.

The session address binding layer supports simultaneous binding of sessions to both IPv4 and IPv6 addresses so clients may use both types and float between them.

V4.2+ introduces an additional option to support arbitrary string values as "addresses", produced by a strategy function of type Function<ProfileRequestContext,String> defined with the bean ID shibboleth.SessionAddressLookupStrategy. The absence of this bean relies on the servlet container's REMOTE_ADDR value as in prior versions. For now, it is necessary that values returned by this function NOT contain periods or colons so as to avoid confusing the system into treating the value as an IP address. This limitation may be addressed in the future. Encoding the string is a means of avoiding the problem.

Note that this alternative "address" feature is NOT a substitute for proper web server configuration in the event of proxying. If you try that, the IdP will break in other places because there are lots of dependencies on being able to obtain the proper address from the web server.

Session Timeouts

In many cases an SSO deployment must satisfy policy requirements around how frequently users must reauthenticate. There are three properties that generally determine authentication frequency:

idp.session.timeout (default PT60M)
idp.authn.defaultLifetime (default PT60M)
idp.authn.defaultTimeout (default PT30M)

Note that the latter two, being authentication-related were moved to conf/authn/authn.properties in V4.1+, but may remain in idp.properties on upgraded systems. The exact location doesn't matter, all properties are loaded as a set.

Under the default configuration, user authentication occurs hourly except in cases where the IdP session (and thus any contained authentication result) is idle for more than 30 minutes. Note that some authentication methods may be non-interactive such that users don't actually have to explicitly provide credentials (IPAddress, X509Internal), but an authentication event is nonetheless occurring hourly under the default configuration.

Simple Session Lifetime Example

An example may be helpful in further clarifying how session configuration defines security policy around user authentication. Suppose a deployer wants to implement the following security policy:

Users must authenticate at least once daily.
An IdP session may remain idle at most for 1 day.

# IDP session timeout must be at _least_ as long as authn result lifetime
idp.session.timeout=PT24H

# Authentication results live for at most 24 hours
idp.authn.defaultLifetime=PT24H
 
# Authentication results may be idle for at most 60 minutes
idp.authn.defaultTimeout=PT60M

Advanced Session Lifetime Example

In some cases it may be permissible to allow some authentication methods to have longer lifetimes than others; for example, an authentication result produced by a hardware token may be valid for a day whereas that of a password credential is valid for an hour. These policies are accommodated by defining a conservative idp.authn.defaultLifetime and more liberal periods for specific authentication methods. A hypothetical security policy follows with the configuration required to implement it.

Users must authenticate every hour using a password credential
Users must authenticate daily using a hardware token containing an X.509 certificate
An IdP session may be idle for at most 1 day under any circumstances

 # IDP session timeout must be at _least_ as long as longest authn result lifetime
idp.session.timeout=PT24H
 
# Conservative default authentication result lifetime is 60 minutes
idp.authn.defaultLifetime=PT60M
 
# Defines idle time on authentication results. Not overridden per authn method in this case.
idp.authn.defaultTimeout=PT60M

conf/authn/general-authn.xml

    <util:list id="shibboleth.AvailableAuthenticationFlows">
        <bean id="authn/Password" parent="shibboleth.AuthenticationFlow"
                p:passiveAuthenticationSupported="true"
                p:forcedAuthenticationSupported="true" />

        <bean id="authn/X509" parent="shibboleth.AuthenticationFlow"
                p:forcedAuthenticationSupported="true"
                p:nonBrowserSupported="false"
                p:lifetime="PT24H">
            <property name="supportedPrincipals">
                <util:list>
                    <bean parent="shibboleth.SAML2AuthnContextClassRef"
                        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:X509" />
                    <bean parent="shibboleth.SAML2AuthnContextClassRef"
                        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient" />
                    <bean parent="shibboleth.SAML1AuthenticationMethod"
                        c:method="urn:ietf:rfc:2246" />
                </util:list>
            </property>
        </bean>
    </util:list>

conf/authn/authn.properties

Reference

Session-related properties are generally defined in conf/idp.properties

Worthy of note, you can switch to server-side storage of user sessions by setting the idp.session.StorageService property to shibboleth.StorageService, or an alternative defined by you. This is generally ill-advised in most cases if you operate more than one server node, as the client-side mechanism is much more reliable for clustering than any other approach.

Property / Type	Default	Function

Property / Type	Default	Function
idp.session.enabled Boolean	true	Whether to enable the IdP's session tracking feature
idp.session.StorageService Bean ID of StorageService	shibboleth.ClientSessionStorageService	Bean name of a storage implementation/configuration to use for IdP sessions
idp.session.cookieName ^4.2 String	shib_idp_session	Name of cookie containing IdP session ID (note this is not the same as the cookie the Java container uses to track its own sessions)
idp.session.idSize Integer	32	Number of characters in IdP session identifiers
idp.session.consistentAddress Boolean	true	Whether to bind IdP sessions to IP addresses
idp.session.consistentAddressCondition BiPredicate<String,String>	Direct string comparison	A 2-argument predicate that compares a bound session's address to a client address
idp.session.timeout Duration	PT60M	Inactivity timeout policy for IdP sessions (must be non-zero)
idp.session.slop Duration	0	Extra time after expiration before removing SP sessions in case a logout is invoked
idp.session.maskStorageFailure Boolean	false	Whether to hide storage failures from users during session cache reads/writes
idp.session.trackSPSessions Boolean	false	Whether to save a record of every SP accessed during an IdP session (requires a server-side session store or HTML LocalStorage)
idp.session.secondaryServiceIndex Boolean	false	Whether to track SPs on the basis of the SAML subject ID used, for logout purposes (requires SP session tracking be on)
idp.session.defaultSPlifetime Duration	PT2H	Default length of time to maintain record of an SP session (must be non-zero), overridable by relying-party-specific setting

Name	Type	Description

Name	Type	Description
shibboleth.SessionAddressLookupStrategy	Function<ProfileRequestContext,String>	Alternate source of a client "address" to replace the default behavior relying on REMOTE_ADDR. May be defined in global.xml if needed.
shibboleth.DefaultPrincipalSymbolics	Map<String,Integer>	Default mappings that shrink authentication result data by storing commonly seen strings as numbers, this is an internal default that can be viewed in the sources.
shibboleth.PrincipalSymbolics	Map<String,Integer>	User-supplied list of values to merge into shibboleth.DefaultPrincipalSymbolics bean. May be defined in global.xml if needed.