Child pages
  • Upgrading 2.x Shibboleth SP to 3.x
Skip to end of metadata
Go to start of metadata

Shibboleth SP 3.x has been released in August 2018.  While it aims to be compatible with existing 2.x configuration, there are several points that need attention:

  • Shibboleth SP 3.x by default generates separate signing and encryption certificates for new installations.  While existing deployments can continue using the single signing+encryption certificate, it is important to be aware of this change.
  • Shibboleth SP 3.x introduces a new XML schema for the configuration file.  This schema uses a different namespace and removes some deprecated features used in the old schema.  For easier transition, SP 3.x can also read configuration files still using the old 2.x schema - but this should be seen just as a temporary measure and the configuration should be properly migrated to the new schema.

For further information on the changes, please see the Shibboleth SP 3.x Release Notes and the UpgradingFromV2 page.

This page gives the upgrade sequence recommended by Tuakiri.

Backup and package update

  • Create a backup of /etc/shibboleth/ - this will turn useful when later inspecting the local configuration changes.

    cp -R -p /etc/shibboleth /root/shibboleth-etc-2.6
  • Upgrade the packages with the system package manager.  On RHEL/CentOS systems, use yum upgrade  -or to upgrade just Shibboleth SP and to leave other package updates to your regular processes, use:

    yum --disablerepo='*' --enablerepo=security_shibboleth update
  • Delete older versions of dependent library packages:

    yum remove liblog4shib1 libsaml9 libxerces-c-3_1 libxml-security-c17 libxmltooling7

     

     

As of September 7th, 2018, SP 3.x is still not available for Debian/Ubuntu systems - a release is expected during this month.

Resolve configuration file modification clashes

The package update process will report clashing changes - configuration files updated both locally and in a newer version of the package.

These will likely include:

warning: /etc/shibboleth/attribute-map.xml created as /etc/shibboleth/attribute-map.xml.rpmnew
warning: /etc/shibboleth/native.logger created as /etc/shibboleth/native.logger.rpmnew
warning: /etc/shibboleth/shibboleth2.xml created as /etc/shibboleth/shibboleth2.xml.rpmnew

Resolve them the following way:

  • native.logger: the local changes recommended in earlier versions of the Installing Shibboleth SP on RedHat based Linux manual are no longer needed.  Just revert to the default version of the file:

    mv -f /etc/shibboleth/native.logger.rpmnew /etc/shibboleth/native.logger
  • attribute-map.xml: If running with stock Tuakiri Attribute Map, update the file (and drop attribute-map.xml.rpmnew )

    wget -O /etc/shibboleth/attribute-map.xml https://github.com/REANNZ/Tuakiri-public/raw/master/shibboleth-sp/attribute-map.xml
    rm -f /etc/shibboleth/attribute-map.xml.rpmnew

     

    • Alternatively, start from /etc/shibboleth/attribute-map.xml.rpmnew and port over local customizations
    • You can see these with:

      diff -u /root/shibboleth-etc-2.6/attribute-map.xml{.dist,}
  • shibboleth2.xml: we recommend starting from a fresh new copy of the file (created as shibboleth2.xml.rpmnew) and porting over into this file all changes done in 2.x:
    • Check existing customizations with:

      diff -u /root/shibboleth-etc-2.6/shibboleth2.xml{.dist,}
    • Apply these changes to /etc/shibboleth/shibboleth2.xml.rpmnew (either changes done in 2.x or changes as per the Shibboleth SP Installmanual) - but please consider the following
      • Do not apply the cipherSuites setting - this is no longer necessary, as the default setting is now functionally equivalent to our recommendation.
      • In MetadataProvider, replace uri with url (and add verifyBackup="false" to SignatureMetadataFilter)
      • And, importantly, if keeping the  original combined signing+encryption certificate, replace the default two CredentialResolver entries with just one (not restricted to signing/encryption, so applying to both):

        <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
    • Deploy the new shibboleth2.xml file:

      mv -f /etc/shibboleth/shibboleth2.xml.rpmnew /etc/shibboleth/shibboleth2.xml
  • And finally, force reload of the configuration files by restarting shibd and Apache:

    service shibd restart ; service httpd restart
  • No labels