Upgrade Identity Provider 2.0/2.1/2.2 to 2.3

These instructions are for IdPs versions 2.0, 2.1 and 2.2 in the SWITCHaai federation which have been installed using the deployment guides on our website.

The following instructions assume that the latest Shibboleth Identity Provider has been downloaded and extracted in the directory /usr/local/src/shibboleth-identityprovider-x.y.z.
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
Please also take the time to upgrade the OS, Java and Apache Tomcat. The Shibboleth IdP 2.3 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. In this case $TOMCAT_HOME = /usr/share/tomcat6.

  1. Before doing any changes, backup the configuration files: 
    cd /opt/shibboleth-idp
tar -cvzf ../shibboleth-idp_config.tar.gz ./conf ./metadata ./credentials
  2. Update the customized login pages in the IdP source directory. Also update the web application deployment descriptor file WEB-INF/web.xml. The IdP version installed on your system may be different from the example (2.2.1) below. The customized pages are located in src/main/webapp/. 
    cd /usr/local/src/shibboleth-identityprovider-2.2.1
cp -pr src/main/webapp/* \
/usr/local/src/shibboleth-identityprovider-x.y.z/src/main/webapp/
  3. 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 http://dev.mysql.com/downloads/connector/j/. 
    cp lib/mysql-connector-java-5.1.18-bin.jar \
/usr/local/src/shibboleth-identityprovider-x.y.z/lib/
  4. 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-x.y.z/lib/
    5. 

  5. Update the endorsed libraries in the Tomcat endorsed directory $TOMCAT_HOME/endorsed/:

    rm /usr/share/tomcat6/endorsed/*.jar
cp -p /usr/local/src/shibboleth-identityprovider-x.y.z/endorsed/*.jar \
/usr/share/tomcat6/endorsed/

    

    6. 

  6. 

    Check the autoDeploy parameter in /etc/tomcat6/server.xml. If its value is true, change it to false. Restart tomcat

    

     /etc/init.d/tomcat6 restart 
    

    7. 

  7. 
The file relying-party.xml has changed since previous versions of the IdP. Please review and adapt your relying-party.xml. In particular check Section 11.1.2, Metadata Trust Configuration in the documentation for the changes.

    8. 

  8. Identity Providers using uApprove have to upgrade uApprove as well. Please refer
to the uApprove page for upgrading. 

    In case you have already the latest version of uApprove, anyway you have to copy the plugin libaries into the IdP install directory:

    cp /opt/uApprove-2.x/lib/* /usr/local/src/shibboleth-identityprovider-x.y.z/lib/

    

    9. 

  9. Redeploy the Shibboleth IdP by running the install script:

    cd /usr/local/src/shibboleth-identityprovider-x.y.z
./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)

    

    10. 

  10. 

    
 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

    

    11. 

  11. Restart the servlet container (e.g. with /etc/init.d/tomcat6 restart) in order to restart the Identity Provider.
    12. 

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