Upgrade the Shibboleth Identity Provider from 2.0/2.1/2.2/2.3 to 2.4

These instructions are for IdPs versions 2.0/2.1/2.2/2.3 in the SWITCHaai federation that have been installed using the deployment guides on our website.

Please also take the time to upgrade the OS, Java and Apache Tomcat. The Shibboleth IdP 2.4 runs well on Tomcat 6.
We assume that this is the version you use and that you have installed it from the debian package tomcat6.

If you run version 2.4.x of the Shibboleth Identity Provider:

Note

If you already run version 2.4.x of the Shibboleth Identity Provider, please follow the upgrade instructions as detailed in Upgrade the Shibboleth Identity Provider from 2.4.x to 2.4.4 instead.

If you run a version before 2.3.x of the Shibboleth Identity Provider:

Warning

If you are running an Identity Provider version less than 2.3.x, we highly recommend to do a fresh installation instead of performing an upgrade. To do this, follow our installation guide. You can then re-use your attribute-resolver.xml configuration and the existing customized login and error pages in src/main/webapp/ of the Shibboleth IdP distribution (/usr/local/src/shibboleth-identityprovider-x.y.z).

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:

Preparations for Upgrade from 2.0/2.1/2.2

Earlier guides unpacked the Shibboleth IdP sources to /opt. This guide assumes that all Shibboleth IdP sources are unpacked to /usr/local/src.

To clean up, move the previous version of the IdP into /usr/local/src instead of keeping it in /opt.

 mv /opt/shibboleth-identityprovider-* /usr/local/src 

Preparations for Debian 7.0 "wheezy"

If you have upgraded your Debian operating system to the current stable version Debian 7.0 "wheezy", we recommend that you install the Java package default-jre-headless. This will install OpenJDK. Java will be available in /usr/lib/jvm/default-java.

apt-get install default-jre-headless

Notes

Upgrade Instructions

  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.

    The following steps assume that the latest Shibboleth Identity Provider has been downloaded and extracted in the directory /usr/local/src/shibboleth-identityprovider-2.4.4:

  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 IdP version currently running on your system may be different from the example (2.3.8) below. The customized pages are located in src/main/webapp/.
    cd /usr/local/src/shibboleth-identityprovider-2.3.8
    cp -pr src/main/webapp/* \
      /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/
  4. Check some settings in the file src/main/webapp/WEB-INF/web.xml:

    cd /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/WEB-INF
  5. Update the file src/main/webapp/WEB-INF/idpui.tld by downloading it from our website.

    cd /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/WEB-INF
    curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/idpui.tld
    
    Note: Usually, no manual changes have been made to this file. So it's safe to just replace the existing file.

  6. 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.)

  7. In case you use CAS, an optional local single-sign-own system, copy also the cas-client JAR file in 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/
  8. Remove the previously used Tomcat endorsed subdirectory (must no longer be used with IdP 2.4.4 or later, for security reasons):
    rm -r /usr/share/tomcat6/endorsed
    
  9. The file relying-party.xml has changed at various places since previous versions of the IdP. We highly recommend to download the SWITCHaai specific relying-party.xml file as a template from our website and apply the required adaptations as described in our deployment guide.

    WARNING: The following instructions install a new version of the file relying-party.xml and replace the old file. In case you have made specific manual changes to the existing file, please carefully compare the old and the new file. If you have enabled interfederation support in the old file, you can still use the new file and just re-enable interfederation support by removing the comments around the corresponding MetadataProvider and TrustEngine elements. If in doubt, try to keep the existing file or ask the SWITCHaai Team for support.

  10. Update all of the following configuration files by downloading them from our website:

    WARNING: The following instructions install new versions of the these files and replace the old files. In case you have made specific manual changes to the existing files, please carefully compare the old and the new files. If in doubt, try to keep the existing files or ask the SWITCHaai Team for support.

    cd /opt/shibboleth-idp/conf/
    cp handler.xml handler.xml.old
    cp internal.xml internal.xml.old
    cp service.xml service.xml.old
    curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/handler.xml
    curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/internal.xml
    curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/service.xml

    Note: In the file service.xml, you need to adapt the URL to downlad the attribute-filter.xml file. This is described in the next step.

  11. In the just downloaded file service.xml, update the URL to download the attribute-filter.xml file. The correct download URL has to be obtained from the SWITCH Resource Registry. (Login to the Resource Registry, go to "Home Organizations", and locate your Home Organisation. The link to the download location of attribute-filter.xml is labelled as "Attribute Filter".)

    Edit the file service.xml, look for the element <srv:Service id="shibboleth.AttributeFilterEngine" ...> and change the value of the url attribute to the URL found in the Resource Registry.
    <srv:Service id="shibboleth.AttributeFilterEngine"
      xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine"
      configurationResourcePollingFrequency="PT1H"
      configurationResourcePollingRetryAttempts="128">
      <srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource"
        url="https://rr.aai.switch.ch/switchaai/example.org/attribute-filter.xml"
        file="/opt/shibboleth-idp/conf/attribute-filter.xml"/>
    </srv:Service>

  12. Add support for internationally used attributes. These attributes are required by some international Federation Partners (e.g. publishers). SWITCH recommends to add these attributes as they will ensure that users in SWITCHaai can access international services and that international collaboration becomes easier.

    This step also enables your Identity Provider to add the value member to the attribute eduPersonAffiliation for users who have one of the values student, staff or faculty set. The value member is required by some international Federation Partners.

    At least, you should make sure that

    Without this, your users might not be able to access the services of some publishers.

    Follow the guide International Attribute Support for SWITCHaai Identity Providers to add these attributes.

    Note: You won't need to restart your Identity Provider at this step as described in the guide above, since this will be done later in this guide.

  13. If you have uApprove installed (module for user attribute release consent), you might have to upgrade uApprove as well.
  14. If you upgrade from IdP version 2.0/2.1, check the LDAP filter of the LDAP connector in your attribute-resolver.xml configuration (element <dc:FilterTemplate> in the LDAP DataConnector). You might need to adapt the filter according to the descriptions in the Shibboleth Wiki IdP2.2 upgrade instructions (Changes in Principal Name Returned from Authentication). (Since IdP version 2.2, the IdP sets the variable $requestContext.principalName to the user's login ID (the thing they type in the username field of the login page) instead of the value returned by the authentication engine.)
  15. Update the logging configuration in the file logging.xml. We recommend to limit the archivation of log files to a maximum of 6 months.

    We provide an adapted configuration file logging.xml you can download and use. This configuration file limits the archivation of log files to a maximum of 6 months and adapts some settings that are not optimal in the default configuration.

    WARNING: The following instructions install a new version of the file logging.xml and replace the old file. In case you have made specific manual changes to the existing file, please carefully compare the old and the new file. If in doubt, try to keep the existing file or ask the SWITCHaai Team for support.

    Our specific logging.xml file can be downloaded as follows:

    cd /opt/shibboleth-idp/conf/
    cp logging.xml logging.xml.old
    curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/logging.xml
    

    (If you upgrade from IdP version 2.0/2.1, and want to keep your existing logging configuration, please apply the changes in the Shibboleth Wiki IdP2.2 upgrade instructions (Logging Configuration).)

  16. Redeploy the Shibboleth IdP by running the install 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
    

    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)
    
  17. Set appropriate ownership and permissions for the files in /opt/shibboleth-idp/.

    cd /opt/shibboleth-idp
    chown -R tomcat6 logs metadata 
    chgrp -R tomcat6 conf credentials logs metadata war lib
    chown tomcat6 conf/attribute-filter.xml
    chmod 664 conf/attribute-filter.xml
    chmod 755 lib war
    chmod 755 conf credentials
    chmod 640 conf/logging.xml
    chmod 640 conf/attribute-resolver.xml
    chmod 644 conf/attribute-filter.xml
    chmod 755 logs metadata
    cd credentials
    chown root idp.key
    chgrp tomcat6 idp.{key,crt}
    chmod 440 idp.key
    chmod 644 idp.crt
    rm -f idp.jks
    
  18. Check the autoDeploy parameter in /etc/tomcat6/server.xml. If its value is true, change it to false.

  19. Restart Tomcat in order to restart the Identity Provider.
  20.  /etc/init.d/tomcat6 restart 
  21. 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/