LogoutConfiguration

File(s): conf/idp.properties, views/logout.vm, views/logout-complete.vm, views/logout-propagate.vm

Single Logout (SLO) support is new in 3.2.0. SLO is a best-effort attempt to end relying party sessions without clearing the browser's cookie and storage state. Most browsers do not clear this state when closed.

Proprietary/Simple Logout

Overview

When an HTTP GET request is made to the /profile/Logout endpoint with a valid IdP session cookie, the corresponding IdP session is ended and the logout.vm view is rendered that informs the user of the following:

The IdP session is ended.
Lists all services accessed during the IdP session, if tracked, and offers to end those sessions by propagating a logout message to each one.

If the user chooses SLO, the logout-propagate.vm view is rendered and the browser mediates (i.e. front-channel) a series of logout messages coordinated via iframes, javascript, and in some cases HTML5 storage. The result is a best-effort attempt to explicitly end each relying party session by sending a protocol-specific message to each service endpoint. In the IdP configuration, the SLO messaging process is called propagation. The IdP attempts to display prominent status information on the result of each attempt to end a relying party session; a red X for failure or a green checkbox for success.

If the user chooses to end without SLO, logout-complete.vm is rendered and a message is displayed indicating that some relying party sessions may still be active.

At present, the IdP session is terminated regardless of the user's choice. In other words, the question asked is "propagate or not?" rather than "logout or not?". The implications of this have been the subject of mailing list discussion and additional flexibility may be developed for future releases. You may also choose to copy and adapt the system-supplied logout flow locally to behave differently if you want to do that work.

Configuration

The following property in idp.properties must be enabled to support the SLO propagation feature.

Required IdP Properties

# Track information about SPs logged into
idp.session.trackSPSessions = true

The default storage solution used for session is based on cookies and does not support the SP tracking feature. You can either enable the use of HTML LocalStorage, which does support that feature, or switch to a server-side storage service option. See the StorageConfiguration topic for information on either of these approaches.

If you want the displayed information about services to be customized by the use of SAML metadata (for things like service names and logos), you should also set the following property:

Optional IdP properties

# Whether to lookup metadata, etc. for every SP involved in a logout
# for use by user interface logic; adds overhead so off by default.
idp.logout.elaboration = true

In order for CAS protocol services to participate in SLO, the singleLogoutParticipant attribute must be set to true in the service definitions that identify the service:

CAS Registered Service Example

<bean class="net.shibboleth.idp.cas.service.ServiceDefinition"
      c:regex="https://([A-Za-z0-9_-]+\.)*example\.org(:\d+)?/.*"
      p:group="slo-services"
      p:authorizedToProxy="false"
      p:singleLogoutParticipant="true" />

In order for SAML services to participate in SLO, the SAML metadata supplied for them must contain appropriate <SingleLogoutService> endpoints. In addition, SPs vary in how they handle security, and SLO is in general vastly less interoeprable than SSO in SAML, so you should not expect uniform results. Shibboleth itself assumes that all logout messages are signed, and if you need to interoperate with SPs that don't sign their logout responses, you will need to set the following property:

Optional IdP properties

# Whether to require logout requests/responses be signed/authenticated.
idp.logout.authenticated = false

UI Considerations

The look and feel of the logout process can be changed through modification of the view templates, message properties, etc.

Some deployers may choose to make SLO mandatory, which would require modifying the <head> content of logout.vm as follows:

Always Perform SLO

#if ( $logoutContext and !$logoutContext.getSessionMap().isEmpty() )
    <meta http-equiv="refresh" content="0;url=$flowExecutionUrl&_eventId=propagate">
#end

The SLO machinery is a fairly complex interaction between embedded iframes and javascript that drives and processes logout messages. That logic, due to its complex and fragile nature, is confined to a system view file, idp/system/views/logout/propagate.vm. Modification of that file is discouraged and will not survive upgrades.

Browser Support

The SLO feature requires a fair bit of mature Javascript support, but any browser that supports HTML5 LocalStorage should work (this use of LocalStorage is independent of the choice of storage service, it applies even when server-side storage is used). While the SLO implementation is based on modern Web standards, browser features vary so greatly that it's hard to identify minimum browser requirements. To underscore the point, we identified a problem caused by the inability of IE to recognize the application/json media type (IDP-879) in the SLO support that shipped in V3.2.0.

SAML Logout

SAML Logout is a more complex protocol than the simple variant described above, but the implementation is shared across the two approaches. There are really two "halves" to this:

Responding to requests from an SP
Propagating logout to an SP

This section is about the first case. The propagation step is covered in the previous section and is the same, regardless of how the logout is initiated.

SPs can request a logout using either front- or back-channel SAML bindings (typically HTTP-Redirect on the front, SOAP on the back). The IdP supports reception of either type of request, but currently cannot propagate logout using SOAP (but if you rely on a server-side session storage option, it can terminate the session at the IdP).

Configuration

The following property in idp.properties must be enabled to support SAML logout requests:

Required IdP Properties

# Support lookup by SP for SAML logout
idp.session.secondaryServiceIndex = true

The default storage solution used for session is based on cookies and does not support the secondary indexing feature. You can either enable the use of HTML LocalStorage, which does support that feature, or switch to a server-side storage service option. See the StorageConfiguration topic for information on either of these approaches. Of course, using the client-side storage option does not allow for back-channel logout.

Another consideration with SAML logout has to do with the length of time the system will "remember" the SP's session, in order to prevent the session cache from growing endlessly. This can't be done precisely because the IdP doesn't actually know how long the SP's own session might last. The idp.session.defaultSPlifetime and idp.session.slop properties control how long the IdP will "remember" an SP's session. Once elapsed, it's likely that a request for logout will fail from any SP that has expired from the cache.