CAF – Shibboleth v4 Upgrade Guidance

Regardless of the platform you use, keeping current on your Identity Provider (IdP) software is a vital factor in your organization’s security practices. This guidance highlights upcoming end-of-support in December 2020 for Shibboleth IdPs older than v4.0.1 and aims to assist navigating various upgrade pathways.

As you plan your update, it is a great opportunity to review new features in the Shibboleth IdP to see if they help advance you on your technology roadmap. The IdP is a pivotal security component in your identity and security architecture that touches:

  • Authentication
  • Authorization
  • Attribute release
  • Streamlining service activation with multi-lateral federation trust

Shibboleth IdP Version 4.0.1 offers the same stability and performance with newly added capabilities such as SAML proxying and OpenID Connect (OIDC) support as an OIDC Provider (OP), while continuing to allow ways to weave in multi-factor flows for your services.

NOTE: For detailed guidance consult wiki. We strongly urge you to review their Installation material to familiarize yourself with the general process. Most importantly, please review the Release Notes carefully for any important changes you might need to account for or make in advance of an upgrade.

In general, you should not be required to make changes prior to an upgrade, but security issues or other major bugs occasionally require special care.

Where to Start

Your starting point and how far along you want to be on your technical roadmap will dictate the steps involved in upgrading. Having a clear target outcome will help you develop your plan and set you on the right path. Here are some starting points and common questions to assist you in navigating your upgrade path.

Key Recommendations from the Shibboleth Consortium

The Shibboleth Consortium software update model follows an “update in place” approach. We strongly encourage sites to read the Shibboleth Upgrading guidance and deploy to a test IdP environment to learn and validate before applying the upgrade steps to your production environment.

Three critical factors that will influence upgrades:

  1. If you are upgrading from a pre-V4 release, you must first upgrade to the latest V3 release and remove all deprecation warnings.
  2. You must ensure that your versions of Java and servlet container meet the system requirements for V4. If they do not, you should upgrade those before attempting to upgrade the IdP software.
  3. Java 11 is now required. Jetty 8 was sufficient to run IdP V3 but IdP V4 requires Jetty 9.4+.

How to Approach Your Upgrade

Sites currently running Shibboleth v3.4.7 should continue with the upgrade keeping in mind the considerations discussed above. Many of the steps below may already be underway.

Sites running older versions (prior to v3.4.7) may face additional challenges. The biggest challenge is that older Shibboleth IdP versions are unable to resolve deprecations easily and present several obstacles to upgrading to v4.0.1.

If you are running an older version, we recommend that you:

  • Provision a new system (on a current/hardened OS) for your test and production systems
  • Choose an installation technique for IdP v4
  • Bring forward your site settings into a test IdP capturing changes that need to be applied to production.
  • Test first in CAF test federation, then with new production host

IdP Installation Techniques

  • Sites can deploy the IdP directly on a VM by following the installation This allows you to leverage the OS package management to ensure the correct Java version is installed from a known and trusted repository and kept current with less effort.
  • Sites seeking a more contemporary model should consider the Internet2 Trusted Access Platform containers for the IdP.

You can determine if you want to pursue a Docker container model for operating your IdP. The container’s repository maintains the latest Shibboleth v4 software and you can apply the CAF settings to your container deployment.

Preserving Continuity During Upgrade

In many cases, upgrades assume the role and name of the existing service. Key considerations to ensure a smooth upgrade are:

  • Do not change your entityID or you will invalidate existing rules others may have defined
  • Copy your production SAML signing key into the new instance to ensure signatures and encryption/decryption processes are preserved
  • Do not change your SAML protocol endpoints or users and services will fail

Preserve any special salt secrets used for calculating unique ID, otherwise you will invalidate linkages to users as they sign into various services.  The “salt” is random data that is used as an additional input to a one-way function that hashes data to defend against a pre-computed hash attack. In this case, the calculation of unique identifiers in the Identity Provider.

Seamless Upgrade Strategies

By following the recommendations described above, your upgraded pre-production environment testing can proceed by overriding a local host’s file for you and your test users. This enables accurate side-by-side production/pre-production testing of the upgrade path and a clear fallback position in case of problems. It also means that this upgrade can occur transparently to both CAF, your users, and the Service Providers you interact with.

Embracing New Features in New Versions of Shibboleth

Organizations also have an opportunity to advance their technical roadmap by taking advantage of new features and capabilities of this latest release of Shibboleth IdP. Commonly requested features include OIDC support and the ability to leverage Azure AD authentication, which is now possible via the SAML proxy feature of the Shibboleth IdP.

Open ID Connect (OIDC) Identity Provider (OP) Support

OIDC Support enables the Shibboleth IdP to become an OIDC identity Provider (OP), details of which can be found here. To take advantage of this new feature, the upgrade to v4.0.1 should be complete before implementing the OIDC OP feature set. This more advanced activity is not in scope for an upgrade document. We recommend reviewing the Shibboleth wiki for more details.

SAML Proxying

SAML proxy support is now a core feature of the Shibboleth IdP. Using the Shibboleth IdP as a proxy means that the IdP can, in a trustworthy way, leverage and re-use the sign-on experience of another Identity Provider and repeat the sign-on attributes and information and also add or change information as it passes through. This proxying ability is key to connect the Shibboleth IdP to either Azure AD or other Identity providers to leverage their sign on experience. For more details about this approach please contact the CAF technical team at to book a session on the topic.

Azure AD Sign-On with or without MFA with the Shibboleth IdP v4

Azure AD authentication support integrates with Shibboleth via the SAML proxying feature.  There are various configurations that can be put into play largely revolving around how much institutional data is available in Azure AD and the desired sign-on experience.  For more details about this approach please contact the CAF technical team at to book a session on the topic.