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

Table of contents

  1. No entry yet.

Note

  • This guide focusses on SAML Single Logout (SLO) for a Shibboleth SP in combination with the SWITCH edu-ID IdP as well as all IdPs of the organizations that adopted SWITCH edu-ID.
  • In addition, it provides generic hints regarding Single Logout in further scenarios.

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. Your SP needs to support the SWITCH edu-ID private identity:
    Check out your SP's entry in the AAI Resource Registry with the Resource Inspector to disply the configuration details: View Resource screenshot from Resoure Registry
    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. 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.

Adapt your SP for Single Logout

To tailor this guide, enter the hostname of your SP and pick its entry from the auto-completion pop-up list. It will work for the SPs registered in either the SWITCHaai or the AAI Test Federation.

  • SP EntityID:
  • SP Name:
Default Session Initiator Location: /Login /DS (up to Shibboleth SP 2.4.x '/DS' was the default value)

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'

Verify in shibboleth2.xml whether in all the <Sessions> elements of your configuration the attribute redirectLimit is set.
Its default setting redirectLimit="none" does unfortunately not prevent open redirect misuse. See the the Shibboleth Wiki for all the options available.
Set it in all the <Sessions> elements to redirectLimit="host" to limit redirects to your own host. This will prevent 'Open Redirect' misuse with the Logout Handler.
<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:
    Service Location screenshot from Resoure Registry
    While you are in the AAI Resource Registry, check whether the Intended Audience setting for the SWITCH edu-ID Private Identity is correctly set to included. If not, fix it: Intended Audience screenshot from Resoure Registry
    Click on submit for approval to finally activate the changes you applied to the entry in the Resource Registry. You will be able to test it, once the change is approved and the SWITCH edu-ID IdP has loaded the new metadata.

Tailor the logout messages for your SP

The Shibboleth SP provides in the /etc/shibboleth directory three template HTML files you can tailor to your needs:
  • 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.
All tests successfully completed?