SAML Flows for Logout

This chapter describes the supported flows for SAML logout based on our sample setup. The SAML logout flows are best-effort; successful execution cannot be guaranteed.

Be aware of the following limitations:

1. SAML SPs must use the same endpoints for their assertionConsumerService and their singleLogoutService.
   1. This is the case if the SP is provided by Nevis, but can be problematic when integrating a third-party SP.
   2. Contact support if you want to integrate an SP that requires the use of different URLs for these two endpoints.
2. There is no feedback to the user if the session was successfully terminated for all affected parties.
   1. This can be improved by adapting the Javascript that is included in the default nevisLogRend template (see macros.vm).
3. The internal nevisProxy Login Renderer pattern cannot be used as it is not able to inject the Javascript required to distribute SAML messages.
   1. Use the nevisLogrend pattern instead if you want to support SAML logout flows.

IDP-Initiated SAML Logout

IDP-initiated SAML logout works as follows (the numbers of the steps below correspond with the numbers in the figure above):

1. Logout is initiated by sending any HTTP request to a logout location of the SAML IDP. The SAML IDP provides two such locations:
   1. <path>/logout - logout with confirmation
   2. <path>/?logout - logout without confirmation
   3. Here <path> stands for any Frontend Path entered in the SAML IDP pattern.
2. The SAML IDP responds as follows:
   1. The IdentityProviderState produces an AUTH_CONTINUE response that contains a GUI descriptor.
   2. nevisLogRend transforms the GUI descriptor into an HTML page.
   3. nevisLogRend adds some Javascript (see macros.vm), which takes care of the remainder of this flow.
3. The browser sends a LogoutRequest message to each SP that has participated in this session.
   1. The requests are sent in parallel using AJAX calls.
   2. The LogoutRequest is included as a query parameter SAMLRequest.
   3. The SP terminates the session of the user.
   4. The SP clears any additional cookies used to detect expired sessions. See the Session Expiration features in the SAML SP Realm pattern.
   5. The SP returns a LogoutResponse. The default Javascript simply ignores these messages.
4. Once all SPs have been informed, the user is sent to a logout URL.
   1. The default logout URL is the root location ( / ) of the virtual host that runs the SAML IDP.
   2. You can use the Logout pattern to change the logout URL.

SP-Initiated SAML Logout

SP-initiated SAML logout works as follows (the numbers of the steps below correspond with the numbers in the figure above):

1. Logout is initiated by sending a request to an application URL with the query parameter logout.
   1. Example: https://www.siven.ch/myapp/?logout
   2. The request is intercepted by nevisProxy and does not reach the application.
   3. The IDP is determined and the corresponding ServiceProviderState returns a LogoutRequest.
2. The browser is instructed to send a LogoutRequest to the SAML IDP.
   1. This request is typically sent using a POST request.
   2. The request is validated by the SAML IDP (IdentityProviderState).
3. The SAML IDP answers as follows:
   1. The IdentityProviderState produces an AUTH_CONTINUE response which contains a GUI descriptor.
   2. nevisLogRend transforms the GUI descriptor into an HTML page.
   3. nevisLogRend adds some Javascript (see macros.vm), which takes care of the remaining flow.
4. The browser sends a LogoutRequest message to each additional SP that has participated in this session.
   1. The requests are sent in parallel via AJAX calls.
   2. The LogoutRequest is added as a query parameter SAMLRequest.
   3. The SP terminates the session of the user.
   4. The SP clears any additional cookies used to detect expired sessions.
   5. The SP returns a LogoutResponse. The default Javascript just ignores these responses.
5. The session is terminated at the IDP by sending an additional request with ?logout attached.
   1. This request is also sent in the background using an AJAX call.
   2. This is required to ensure that the session at the IDP is terminated.
6. The user is sent to the SP that has initiated the SAML logout.
   1. The URL contains a LogoutResponse message to signal a successful logout.
7. The SAML SP redirects the user to its logout target.
   1. By default the RelayState (URL of the application) is used and thus a new SAML authentication will be initiated.
   2. You can set a different Logout Target in the SAML SP Realm pattern.