Enable an SP for Single Logout with the Switch edu-ID IdP

Table of contents

1. No entry yet.

Introduction

This guide documents how to configure a Shibboleth SP to support SAML Single Logout in combination with the Switch edu-ID IdP.
Checkout these SLO presentation slides to get an idea about the user experience and the various cases you will need to test.
That slide set also documents why it is not easily possible to achieve a good SLO user experience with a vanilla Shibboleth IdP.

Prerequisites

Deploy single logout on your SP only if it meets the following prerequisites:

1. Your SP serves only a single (virtual) hostname per entityID (this is the default configuration):
   A single entity can have only one well-defined <SingleLogoutService> endpoint per binding.
   Cookies are typically host-based and logout cannot be easily implemented across virtual hosts. Unlike during SSO, a <samlp:LogoutRequest> message cannot specify a particular response endpoint. Therefore, a scenario with multiple virtual hostnames per entityID is not compatible with SAML SLO.
2. No logout link within your web application may be located within an HTML frame.
3. Does your web application manage its own application session?
   
   1. Yes, it manages its own application session:
      ⇒ It must fulfil these additional prerequisites:
      
      1. Your web application needs to be able to terminate its application session once triggered by an external event.
      2. The application session timeout ≤ SP session timeout
      3. The application does not trigger single logout as a result of an idle activity timeout.
   2. No, it is fully protected by the Shibboleth SP, it has no application internal session management but relies on the SAML session as managed by the Shibboleth SP, including logout:
      ⇒ No additional prerequisites to fulfil.
4. If your SP shall support the Switch edu-ID private identity, check out your SP's entry in the AAI Resource Registry with the Resource Inspector to display the configuration details ane make sure it's enabled:
   That way, you can login to your SP with your Switch edu-ID account and properly test Single Logout, unless your SP's access control rules prevent your access ☺.
5. Since v2.6, the Shibboleth SP fulfils the following requirements by default. If you use some other SP implementation, you need to verify yourself that it fulfils them all:
   
   1. The SP must terminate the local user sessions before issuing a <samlp:LogoutRequest>.
   2. The SP must use the HTTP-Redirect binding for SLO.
   3. The SP must sign all SLO <samlp:LogoutRequest> and <samlp:LogoutReponse> messages.
   4. The SP must include the <saml:NameID> element in <samlp:LogoutRequest> messages exactly like it received it from the IdP, including its element content and all XML attributes included therein. It must neither encrypt the <saml:NameID> element.
   Note for Shibboleth SPs: Ensure your SP config does not include signing="back" in the <ApplicationDefaults> element (e.g. from an earlier version). It would override the default signing="conditional" and prevent the signing of a SLO <samlp:LogoutRequest>. See Signing and Encryption in the Shibboelth Wiki.

Adapt your SP for Single Logout

Adapt your web application to handle external logout

You need to apply this step only if your web application handles its own application session. Once implemented, this will fulfil the above prerequisite 3a1).

This step is highly application specific, so we can't provide you a full recipe. The Shibboleth Wiki provides additional information, see: Web Application Adaptation for SLO.
Once you applied the changes to your web application, add a <Notify> element into your shibboleth2.xml file. Add it either within the <ApplicationDefaults> or the <ApplicationOverride> element, depending on where your SP is configured. For details consult the SP Notify page in the Shibboleth Wiki.

1. The application's logout script has
   • first to terminate the user's application session
   • thereafter, it must redirect the user's browser to the URL it got via the return query string parameter.
   That script can easily identify and destroy the application session thanks to the cookies the web browser will send to the script on the front channel, due to the HTTP-Redirect SLO binding. Therefore, configure notification only on the front channel. That is sufficient for the HTTP-Redirect SLO binding.
   The <Notify> element could look like this, provided you named the application's logout script logout.php:

   <Notify Channel="front"
           Location="https:///#PATH_TO#/logout.php" />

2. Make sure that Local logout is configured in shibboleth2.xml, as it should be by default:

   <Logout>Local</Logout>
   

   This will only terminate the local SP session and the application's own session, if properly configured. It will not propagate it as single logout to the IdP.
3. Test local logout according to Test Local Logout with your SP below.

Prevent 'Open Redirect'

<Sessions
        ...
        redirectLimit="host"
        ...>
    ...
</Sessions>

Enable global logout

1. In shibboleth2.xml modify the <Logout> element from:

   <Logout>Local</Logout>
   

   to include global logout via SAML that it will look like this:

   <Logout>SAML2 Local</Logout>
   

   The <Logout> element is either located within the <ApplicationDefaults> or an <ApplicationOverride> element, depending on where your SP is configured.
2. Next, publish the SP's Single Logout capability to the IdP via the federation metadata.
   Go to the AAI Resource Registry and activate in the Service Locations section for your SP the Single Logout Service for the SAML2 HTTP Redirect binding.
   Add there its SAML protocol endpoint:
   
   If your SP shall support the Switch edu-ID private identity, check whether the Intended Audience setting is correctly set to included. If not, fix it now:
   Click on submit for approval to finally activate the changes you applied to the SP entry in the Resource Registry. You will be able to test it, once the change is approved and the IdPs have loaded the new metadata.

Tailor the logout messages for your SP

• localLogout.html
• globalLogout.html
• partialLogout.html

The Shibboleth Wiki documents the usage and tailoring of these template pages. The SP e.g. displays the localLogout.html page when it couldn't find a <md:SingleLogoutService> location in the IdP's metadata and it had to fall back to local logout.

Test Single Logout with your SP

Test Local Logout with your SP

1. Login to your SP to initiate a session by using its Login Handler and choose as Home Organisation to authenticate at the Switch edu-ID IdP:
   Login Link:
   
   
2. Verify with the Session Handler that the SP session is established.
   Session Handler:
   
   
   Example output:

   Miscellaneous
   Session Expiration (barring inactivity): 479 minute(s)
   Client Address: 2001:620:0:44:3a:755d:eeee:ffff
   SSO Protocol: urn:oasis:names:tc:SAML:2.0:protocol
   Identity Provider: https://idp.example.org/idp/shibboleth
   Authentication Time: 2018-08-15T09:17:17.034Z
   Authentication Context Class: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
   Authentication Context Decl: (none)
   
   Attribute
   Meta-displayName: 1 value(s)
   Meta-errorURL: 1 value(s)
   Meta-informationURL: 1 value(s)
   Meta-largeLogo: 1 value(s)
   Meta-organizationURL: 1 value(s)
   Meta-smallLogo: 1 value(s)
   Meta-supportContactDisplayName: 1 value(s)
   Meta-supportContactMailtoURI: 1 value(s)
   givenName: 1 value(s)
   homeOrganization: 1 value(s)
   mail: 1 value(s)
   persistent-id: 1 value(s)
   surname: 1 value(s)
   

3. Check whether the application session was properly initiated.
4. Initiate the local Logout with the Logout Handler.
   Logout Handler:
   
   
5. Verify with the Session Handler above that the SP session no longer exists:
   

   A valid session was not found.
   

6. Verify that this local logout properly terminated the application session as well.

Test Global Logout with your SP

1. Execute steps 1) and 2) of the sequence documented above: Test Local Logout with your SP.
2. Login to a second SP and check its SAML session with the Session Handler. Use e.g. the AAI Attribute Viewer (Session Handler).
3. Initiate Single Logout from the AAI Attribute Viewer via its Logout Handler.
   Once back at the IdP, try both alternatives: Log out of all services as well as Stay logged in.
   
4. Repeat steps i) to iii) by initiating the Single Logout from within your web application.
5. Repeat steps i) to iii) with also logging in to a third SP of your choice that does not support Single Logout.