Upgrade the Shibboleth Identity Provider from 2.4.x to 2.4.4

These instructions are for IdPs versions 2.4.x in the SWITCHaai federation that have been installed using the deployment guides on our website.

Warning

If you upgrade from a version older than 2.4.0, you need to follow the upgrade instructions as detailed in Upgrade the Shibboleth Identity Provider from 2.0/2.1/2.2/2.3 to 2.4 instead.

The upgrade instructions presented here only consider the upgrade from 2.4.x to 2.4.4.

Adjust this guide to your environment

Note

Before reading further, please adjust the versions to your environment. Select the version of the currently installed IdP. This will adjust all versions in this guide accordingly.


Adjust
Version of currently installed IdP:

Upgrade Instructions

Note

The following steps assume that the currently running Shibboleth Identity Provider 2.4.3 was downloaded and extracted in the directory /usr/local/src/shibboleth-identityprovider-2.4.3 and was installed to the directory /opt/shibboleth-idp according to our deployment guide.

  1. Before doing any changes, backup the configuration files:
    cd /opt/shibboleth-idp
    tar -cvzf ../shibboleth-idp_config.tar.gz ./conf ./metadata ./credentials
    chmod 600 ../shibboleth-idp_config.tar.gz
    
  2. Download the latest Shibboleth Identity Provider.

  3. Update the web application (customized login pages, web application deployment descriptor file WEB-INF/web.xml) in the IdP source directory. Copy the files from the old source directory to the new one. The customized pages are located in src/main/webapp/. The following instructions just replace the new webapp directory with your current webapp directory.
    cd /usr/local/src
    rm -rf shibboleth-identityprovider-2.4.4/src/main/webapp
    cp -a shibboleth-identityprovider-2.4.3/src/main/webapp \
      shibboleth-identityprovider-2.4.4/src/main
  4. Copy over the JDBC driver for the persistent identifier database into the source tree of the new IdP version. Consider upgrading the library if there is a new version available on https://dev.mysql.com/downloads/connector/j/. (You can safely replace this library by a new version.)

  5. Optional step for users of CAS:
    In case you use CAS, an optional local single-sign-own system, also copy the cas-client JAR file into the lib directory:
    cp /opt/cas-client-X.Y.Z/cas-client-core/target/cas-client-core-X.Y.Z.jar \
      /usr/local/src/shibboleth-identityprovider-2.4.4/lib/
  6. If you have uApprove installed (module for user attribute release consent), you need to upgrade uApprove as well.
  7. Redeploy the Shibboleth IdP by running the install.sh script:
    cd /usr/local/src/shibboleth-identityprovider-2.4.4
    
    If you use Debian 7.0 "wheezy" and have the package default-jre-headless installed:
    JAVA_HOME=/usr/lib/jvm/default-java ./install.sh
    
    Else, if JAVA_HOME is set in /etc/profile:
    ./install.sh
    
    This will produce an output similar to the following.
    Make sure not to overwrite the existing Shibboleth configuration!
    (You can just press <ENTER> when the script asks "Would you like to overwrite this Shibboleth configuration?".)
    Buildfile: src/installer/resources/build.xml
    
    install:
    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
    Be sure you have read the installation/upgrade instructions on the 
    Shibboleth website before proceeding.
    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
    Where should the Shibboleth Identity Provider software be installed? 
    [/opt/shibboleth-idp]
    
    The directory '/opt/shibboleth-idp' already exists.  Would you like to 
    overwrite this Shibboleth configuration? (yes, [no])
    no
    
    (further output omitted)
    
  8. Adapt the internal.xml configuration file so that the Apache Xerces2 library is no longer referenced (addresses the CVE-2013-4002 DoS vulnerability):
    perl -pi -e 's/\Q"org.apache.xerces/"com.sun.org.apache.xerces.internal/' /opt/shibboleth-idp/conf/internal.xml

    This command will change the configuration in internal.xml to use the Java class com.sun.org.apache.xerces.internal.util.SecurityManager instead of org.apache.xerces.util.SecurityManager. (If this change has already been done, the command will actually do nothing.)

    In case Perl is not available on your system (on a Debian system, Perl is available by default), you might just download an updated version of the file internal.xml from the webserver of SWITCH and replace the current file with this new file:

    cd /opt/shibboleth-idp/conf/
    cp internal.xml internal.xml.old
    curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/latest/idp/deployment/internal.xml
    
  9. Remove the Tomcat endorsed subdirectory:
    rm -r /usr/share/tomcat6/endorsed
  10. Restart Tomcat in order to restart the Identity Provider.
  11.  /etc/init.d/tomcat6 restart 
  12. Check the log files of the IdP in /opt/shibboleth-idp/logs/idp-process.log for errors and warning messages. In case of errors or warnings, analyze the problem and try to fix it. If the Identity Provider does not start, look for errors in the servlet container log files (e.g. /var/log/tomcat6/catalina.out).

Test the installation

Finally, test whether your IdP still works as before.

In case you have enabled support for interfederation, you should also verify whether all attributes required for interfederation are released.

Getting Support

If problems occur during the upgrade, or something doesn't work as expected, please contact the SWITCHaai Team by email: aai@switch.ch.

General support website: http://www.switch.ch/aai/support/