CAF – Shibboleth Upgrade Guidance

Updated May, 2024

Keeping your Identity Provider (IdP) software up-to-date is a critical component in your organization’s security practices and your organization’s Security Incident Response Trust Framework for Federated Identity (SIRTFI) standing in the R&E community.

This guidance is intended as a companion to CAF’s software guide and the Shibboleth Consortium’s IdP upgrade guide.

Where to Start

Review and assess your technical roadmap

Upgrading is a great opportunity to review your technology roadmap to determine if there are additional features able to enable on your Identity Provider. This is your opportunity to: 

  • Identify problems or deficiencies with your current IdP  
  • Consider new features such as:
    • Multi-Factor Authorization (MFA) 
    • Proxying to another cloud platform 
    • Assess multi-protocol support needs.  

With this assessment in hand, review the latest Shibboleth IdP upgrade guidance and if you opt to install as new, our IdP installation guidance with the following practices in mind for your upgrade. 


Stability first, then new features…

Stability is easier to achieve when change is incremental. It’s advisable to break down larger or more complex actions into discrete steps to verify them before proceeding to the next.   

Common tasks that benefit from this approach:

  • Changing from one OS to another 
  • Coming current on versions of Java 
  • Changing from VM to containerized approach 
  • Adding a new machine to your IdP cluster 
  • Executing major underlying changes to the OS or webserver  

Next Steps

Helpful Upgrade Practices

The Shibboleth IdP upgrade must be in place. This can be either on the existing machine or preferably, on a clone of the machine or testbed that mirrors production so that the upgrade work can proceed independent of operations until the time to switch is at hand. This allows the new upgraded environment to assume the DNS name at the discretion of the IdP admin.  

If a new service name is used this is not an upgrade but a new IdP installation.

Copying files wholesale from an older IdP to a newly installed IdP will not reliably work. 

Additional considerations for an easier in-place upgrade: 

  • Avoid changing your entityID. It does not allow for the ability to test in place and signals a new installation, not an upgrade.
  • Upgrade Java to latest supported version and update plugins before starting.
  • Ensure your production SAML signing and encryption keys are  preserved between old and upgraded install.
  • Preserve any special salt secrets used for calculating unique ID,this value is used to one-way calculate persistent identifiers which must be calculated identically between updates.

The Seamless Upgrade Technique

An upgraded pre-production environment can be tested 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 occurs transparently to CAF, your users, and the Service Providers you interact with.


Questions? Please reach out to the  CAF technical team at [email protected].