CAF – Upgrading to Shibboleth v3

CAF recommends running the latest Shibboleth v3 Identity Provider software published by the Shibboleth Consortium.

Latest Version of the IdP is  v3.2.1. This means that Shibboleth v2 is a legacy version which will reach end of life support as of July 31, 2016.  After this date no bug fixes, not even security-related bug fixes, will be issued.

To assist CAF participants in the transition to v3 we have assembled resources and guidance on upgrading and recommend starting with:

The Shibboleth V2 End of Life (EOL) of July 31, 2016 is fast approaching. If you haven’t already upgraded to V3 we’ve assembled some upgrade options to help save you time and effort.

There are a number of factors to consider when planning your upgrade; age of the installation, amount of customization, style of configuration and operational management to mention a few.

We recommend the IdP-Installer tool to help automate IdP installation during your upgrade process. Whether you use it exclusively, or as part of a larger more sophisticated approach to upgrading, the IdP-Installer will save you a tremendous amount of time.

The IdP-Installer applies all necessary Shibboleth v3 settings for a reference CAF Identity Provider by default. This in turn allows one to focus on the necessary site tailoring specifics such as look and feel and some certificate management needs.

For previous users of the IdP-Installer your configuration file is portable to the latest version of the Idp-Installer. Just cut and paste your previous configuration file into the import feature of the GUI interface shown below of the installer and click import for your latest up to date configuration to start from.

The IdP Installer is free to use and can be found here.

Upgrade in place or create a new host?

Regardless of your upgrade starting point, a key question is; should it be done ‘in place’ or on a new host and switch over to it?

We strongly recommended that:

  • a new host be used when using the IdP-Installer


  • if doing an upgrade in place using the Shibboleth Installer that a clone of the production system be made to test the experience and adjustments needed.

In either scenario it is easy to perform isolated testing in a test environment or emulating production in a limited release environment without impacting end users.

Alternative Upgrade Approaches

There is more than one way to do an upgrade.  If you choose to do the upgrade via an alternative method we recommend reviewing the Shibboleth Consortium reference material on doing the upgrade.

Additionally, the Internet2 update recommendations closely align with CAF recommendations (minus the inCommon specific URLs and validation certificates of course) and are an excellent reference to consult.

Note well

CAF strongly recommends:

  1. Make sure your entityID does not change.
  2. Use a copy of your production SAML signing key.
  3. Make sure your SAML protocol endpoints do not change.
  4. Make sure you preserve any special SALT secrets used for calculating unique ids.

Service Impact

By working on the upgrade as recommended it can be tested by overriding your local hosts file for you and your test users and be tested side by side to your production environment as shown below. If all goes well there will be no service impact either to your users or Service Providers you connect to.

As well, since you will use your existing keys no changes are required by CAF for your metadata.  All upgrade activities are transparent to CAF, Service Providers and end users until the upgraded host is promoted into production. Fallback to the original IdP is to revert the IP address change and can happen quickly.

Contrasting upgrade approaches

CAF feels that the IdP-Installer is one of the least risk paths for an upgrade as it offers the most reliable way to configure the IdP to a known baseline verified by CAF.  A site can then choose what to tailor or extend.

While the Shibboleth Consortium installer CAN perform an upgrade it is designed for best effort execution and the site is required to do hand editing after the upgrade.  It is possible that certain elements such as persistent identifier calculation and data connectors will need to be hand edited post upgrade.  It will work, but additional work remains that the CAF IdP-Installer already handles. It is recommended that you review each of the Shibboleth configuration files to verify your configuration.