The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

NIIF SLO plugin

A full-featured Single Logout (SLO) implementation, as written by the Hungarian NIIF institute, but rewritten as plugin for the default Shibboleth Identity Provider version 2.4 and later. This way, we do not need to use the outdated NIIF branch of the Shibboleth IdP in order to benefit from the NIIF SLO implementation.

Important: This plugin is based on Shibboleth IdP 2.3.8-slo10 by NIIF institute. For further documentation, see
https://wiki.aai.niif.hu/index.php/Single_Logout_in_Shibboleth_IdP
http://software.niif.hu/

Before installing, please be aware of the difficulties of Single Logout:
https://wiki.shibboleth.net/confluence/display/SHIB2/SLOIssues

Please note: This plugin replaces the Shibboleth IdP 2.4 default SAML2SLO and SAML2LogoutRequestProfile.
For more information on the default implementation, see https://wiki.shibboleth.net/confluence/display/SHIB2/IdPEnableSLO

Download

The extension is hosted at http://www.staff.uni-marburg.de/~haimm/unimr-niif-slo.shib2.2014_08_29.tar.gz

Compatibility

This extension needs at least Shibboleth IdP 2.4.

Please note that due to some limitations in the Shibboleth IdP 2.x session cache (e.g. IdP session timeout), the plugin may not always work as expected. Use at your own risk.

Setup instructions

1) Have a look for the enclosed, precompiled jar file (unimr-niif-slo.jar).

Alternatively, you may compile the source and create a jar file yourself. (This may require additional jars from your Shibboleth IdP.) The source is contained within the src/ directory, but some other directories ( META-INF/ and schema/ ) must also be added to the jar file.

2) Then copy the jar file from step 1 to the lib subdirectory from your Shibboleth IdP's setup directory.

3) Copy the contents of the resources/ directory to your webapp/ directory:

css/main.css
images/failed.png
images/indicator.gif
images/success.png
sloController.jsp
sloQuestion.jsp

(These files may later be customized by you.)

4) In your conf/handler.xml , add the NIIF SLO namespace and schema to the <ph:ProfileHandlerGroup ... > , so it reads like this:

    <ph:ProfileHandlerGroup xmlns:ph="urn:mace:shibboleth:2.0:idp:profile-handler"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:niifslo="http://uni-marburg.de/shibboleth/niif-slo"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:idp:profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd
                            http://uni-marburg.de/shibboleth/niif-slo classpath:/schema/niifslo-schema.xsd">

(Explanation: The prefix "niifslo" is bound to the namespace "http://uni-marburg.de/shibboleth/niif-slo" , while the schemaLocation maps the namespace to its according schema file.)

Now look for some <ph:ProfileHandler xsi-type="ph:SAML2SLO" ... > entries, they should be right above the <ph:ProfileHandler xsi:type="ph:SAML2AttributeQuery" ... > node. If you recently upgraded to IdP 2.4 or did not use the SAML2SLO profile yet, they may still be missing and you must add them manually:

    <ph:ProfileHandler xsi:type="ph:SAML2SLO" inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                       outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact">
        <ph:RequestPath>/SAML2/Redirect/SLO</ph:RequestPath>
    </ph:ProfileHandler>

    <ph:ProfileHandler xsi:type="ph:SAML2SLO" inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                       outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact">
        <ph:RequestPath>/SAML2/POST/SLO</ph:RequestPath>
    </ph:ProfileHandler>

    <ph:ProfileHandler xsi:type="ph:SAML2SLO" inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign"
                       outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
                                                   urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact">
        <ph:RequestPath>/SAML2/POST-SimpleSign/SLO</ph:RequestPath>
    </ph:ProfileHandler>

    <ph:ProfileHandler xsi:type="ph:SAML2SLO" inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
                       outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:SOAP">
        <ph:RequestPath>/SAML2/SOAP/SLO</ph:RequestPath>
    </ph:ProfileHandler>
    
    <ph:ProfileHandler xsi:type="ph:SAML2SLO" inboundBinding="urn:mace:shibboleth:2.0:profiles:LocalLogout">
        <ph:RequestPath>/Logout</ph:RequestPath>
    </ph:ProfileHandler>

Finally, in each <ph:ProfileHandler xsi-type="ph:SAML2SLO" ... > , replace each "ph:SAML2SLO" occurence (there should be 5) with "niifslo:SAML2SLO" , so the NIIF SLO will be used instead of the default Shibboleth SLO.

5) In your conf/relying-party.xml , add the NIIF SLO namespace and schema to the <rp:RelyingPartyGroup ... > element , so it reads like this:

<rp:RelyingPartyGroup xmlns:rp="urn:mace:shibboleth:2.0:relying-party"
                   xmlns:saml="urn:mace:shibboleth:2.0:relying-party:saml"
                   xmlns:metadata="urn:mace:shibboleth:2.0:metadata"
                   xmlns:resource="urn:mace:shibboleth:2.0:resource"
                   xmlns:security="urn:mace:shibboleth:2.0:security"
                   xmlns:samlsec="urn:mace:shibboleth:2.0:security:saml"
                   xmlns:samlmd="urn:oasis:names:tc:SAML:2.0:metadata"
                   xmlns:niifslo="http://uni-marburg.de/shibboleth/niif-slo"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="urn:mace:shibboleth:2.0:relying-party classpath:/schema/shibboleth-2.0-relying-party.xsd
                                       urn:mace:shibboleth:2.0:relying-party:saml classpath:/schema/shibboleth-2.0-relying-party-saml.xsd
                                       urn:mace:shibboleth:2.0:metadata classpath:/schema/shibboleth-2.0-metadata.xsd
                                       urn:mace:shibboleth:2.0:resource classpath:/schema/shibboleth-2.0-resource.xsd
                                       urn:mace:shibboleth:2.0:security classpath:/schema/shibboleth-2.0-security.xsd
                                       urn:mace:shibboleth:2.0:security:saml classpath:/schema/shibboleth-2.0-security-policy-saml.xsd
                                       urn:oasis:names:tc:SAML:2.0:metadata classpath:/schema/saml-schema-metadata-2.0.xsd
                                       http://uni-marburg.de/shibboleth/niif-slo classpath:/schema/niifslo-schema.xsd">

Then, within the <rp:DefaultRelyingParty> node, look for the entry <rp:ProfileConfiguration xsi:type="saml:SAML2LogoutRequestProfile" ... > (if available), delete it and add the following lines instead:

            <rp:ProfileConfiguration xsi:type="niifslo:SAML2LogoutRequestProfile"
                              signResponses="always"
                              signAssertions="never"
                              encryptAssertions="never"
                              encryptNameIds="never"
                              backChannelConnectionPoolTimeout="2000"
                              backChannelConnectionTimeout="2000"
                              backChannelResponseTimeout="5000"  />

(This will later be the place for you to configure the NIIF SLO.)

6) In your metadata/idp-metadata.xml , make sure to add the following bindings within the <IDPSSODescriptor ... > node (right below the <ArtifactResolutionService ... > nodes):

        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/idp/profile/SAML2/Redirect/SLO" />
        
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.com/idp/profile/SAML2/POST/SLO" />
        
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://idp.example.com:8443/idp/profile/SAML2/SOAP/SLO" />

7) In your webapp/WEB-INF/web.xml , look for "IdPSessionFilter" and add the following lines right below the </filter-mapping> node:

    <!--  Add IdP SLO Context object to incoming profile requests -->
    <filter>
        <filter-name>SLOContextFilter</filter-name>
        <filter-class>unimr.shib2.niifslo.SLOContextFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>SLOContextFilter</filter-name>
        <url-pattern>/profile/SAML2/SOAP/SLO</url-pattern>
    </filter-mapping>
    <filter-mapping>
        <filter-name>SLOContextFilter</filter-name>
        <url-pattern>/profile/SAML2/Redirect/SLO</url-pattern>
    </filter-mapping>
    <filter-mapping>
        <filter-name>SLOContextFilter</filter-name>
        <url-pattern>/profile/SAML2/POST/SLO</url-pattern>
    </filter-mapping>
    <filter-mapping>
        <filter-name>SLOContextFilter</filter-name>
        <url-pattern>/SLOServlet</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
    </filter-mapping>
    <!-- END of SLO Context Filter -->

Then, look for "/AuthnEngine" and add the following lines right below the </servlet-mapping> node:

    <!-- SLO Servlet -->
    <servlet>
        <servlet-name>SLOServlet</servlet-name>
        <servlet-class>unimr.shib2.niifslo.SLOServlet</servlet-class>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>SLOServlet</servlet-name>
        <url-pattern>/SLOServlet</url-pattern>
    </servlet-mapping>

    <!-- Servlet for IdP - initiated Logout -->
    <servlet>
        <servlet-name>LogoutServlet</servlet-name>
        <servlet-class>unimr.shib2.niifslo.LogoutServlet</servlet-class>
        <init-param>
            <!-- Path for front-channel single logout profile handler -->
            <param-name>profileHandlerPath</param-name>
            <param-value>/profile/SAML2/Redirect/SLO</param-value>
        </init-param>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>LogoutServlet</servlet-name>
        <url-pattern>/Logout</url-pattern>
    </servlet-mapping>

8) Reinstall your Shibboleth IdP by calling the appropriate install.sh file.

9) Restart tomcat and everything should be fine.

Remember that your Shibboleth SPs must be properly configured to support SAML2 logout. The SPs may also need to reload your IdP's metadata (containing the SLO endpoints) before they are willing to send SAML2 logout requests.

History

29-Aug-2014: First release of the NIIF SLO plugin.

License

The NIIF SLO implementation (as well as this plugin) is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0

Contact

Manuel Haim, haim@hrz.uni-marburg.de