Upgrading from Shibboleth 1.3 SP to Shibboleth 2.x SP

There is no direct upgrade path from Shibboleth 1.3 SP to Shibboleth 2.x (eg. just by running an installation program), and the upgrade cannot be performed completely seamlessly. The requisite libraries can be upgraded in place for some operating systems, but new configuration files must be created because the Shibboleth 2.x configuration syntax is different. Also, Shibboleth 1.3 made attributes available to the environment using header variables, but Shibboleth 2.x by default uses environment variables for this purpose. This means that the attribute names now look as specified in the attribute-map.xml file; this must be taken into account if your application uses attributes released to it. Please see the Shibboleth SP upgrade documentation for more information.

It is also worth reading the Shibboleth guide to best practice in the handling of eduPersonTargetedID at this stage.

Thus it is advisable to configure and test a Shibboleth 2 installation on a separate test or development server first, to determine how to translate configuration files to the Shibboleth 2.x syntax, and take account of differences in environment variables and attribute handling.

Here is a possible procedure. Please read it through and check all linked documentation before you start:

1. Install a new Shibboleth 2.x SP on a different server and with a different entity ID from your Shibboleth 1.3 SP. Base its configuration files on the configuration files of your existing Shibboleth 1.3 SP, but using Shibboleth 2.x syntax and taking account of differences with respect to variables and attributes. Please see the Shibboleth documentation and the UK federation Shibboleth 2.x SP configuration guide.
2. Test your new Shibboleth 2.x SP using TestShib.
3. Register, configure and test your new Shibboleth 2.x SP in the federation.
4. When you are happy that the test server is configured correctly, use the test server Shibboleth 2.x configuration files as a basis to create the configuration files for the production server, adjusting for the appropriate hostname and entity ID, and anything else specific to the production server. Use the same entity ID as the production Shibboleth 1.3 SP.
5. Schedule an upgrade slot for the production server. Take a back-up copy of the Shibboleth 1.3 installation directory, and in particular ensure that you retain copies of the certificate and key files.
6. In your designated upgrade time slot, install the Shibboleth 2.x software on the production server using the method appropriate to your server platform. Please ensure that you familiarise yourself with the Shibboleth documentation appropriate to your operating system before you start, and Ohio State University's upgrade guide also has some useful pointers.
   
   
7. Copy the configuration files that you created in step 4 into place in the Shibboleth 2.x installation directory on the production server. Copy the backed up certificate and key files from the Shibboleth 1.3 installation into the Shibboleth 2.x installation directory and modify the shibboleth2.xml configuration file to refer to them.
8. If configured correctly the new Shibboleth 2 SP will include the same SAML1 endpoints and have the same entity ID as the original Shibboleth 1.3 SP, so it should operate in the UK federation straight away without registering changed metadata. You should check the online automatically-generated SP metadata for confirmation of this.
9. Once it is running satisfactorily, email the UK federation helpdesk with a copy of the Shibboleth 2.x SP's automatically-generated metadata and ask for it to be used to replace the old metadata in the SP registration. The new automatically-generated metadata has many more endpoints, eg. for SAML2 and Discovery Service, which allow the SP's functionality to be improved in future.