Upgrades MUST be done in place!

If you are upgrading, PLEASE follow the directions on the Upgrading page and do NOT install the new version separately and then attempt to apply your old configuration files. You MUST upgrade "in place" by using an installation directory that contains a copy of a previously working configuration of V4.3.1.

Failure to do so will result in a non-working system in the majority of cases because there are absolutely essential differences between the output of the installer in the two cases to prevent your configuration from being altered in unexpected ways.

It is urgent that people heed this warning and attempt to modernize settings (if at all) only after upgrading and verifying the behavior of the system.

Upgrade Plugins First (and Last)

Less critically than the above warning, it’s advisable to upgrade any plugins you may have installed (meaning official plugins using the machinery introduced with V4.1 of the IdP) before upgrading the IdP itself, as this may prevent some extra warning noise in the log (or outright incompatibility issues noted by the installer). Upgrade and test those plugin features, and once those are validated, you can proceed to upgrade the IdP itself.

Usually a major upgrade (this one included) will also require a second step of updating most or all of your plugins afterward, which needs to be done before attempting to start the upgraded IdP, as the old ones will in many cases not be compatible with it. The installer will warn about this and report which plugins are in need of an update.

Please review these release notes before upgrading your system. You should review the notes for all the versions subsequent to the one you're running prior to upgrade, including referring back to older V4 notes.

Known Issues

Note to Developers

If you have extension code, plugins, etc., there are numerous changes to the API (principally at the lowest levels) that require in most cases a reimport of the missing classes. Deleting any missing imports and re-importing them via your IDE will resolve a large number of issues, provided that you have updated your POM appropriately. See Project Layout for an explanation of the layout of the V5 library stack and POM import templates.


5.2.0 (Unreleased)

Changes to Defaults or Behaviors

CAS Service URL Handling

The code used to parse URLs and add the CAS ticket parameter to the end was based on a Spring class that has been implicated by 3 separate security issues in the last few years. We have remediated this code to use the same URL parsing and re-encoding class used in the SAML code, but it is very likely this change could impact badly-behaved applications and URLs that, shall we say, “push” the boundaries of what’s legal.

We don’t know exactly what edge cases Spring supported, so it’s difficult to say what the impact of this change will be. We would encourage testing of this release if you use CAS, to make sure any unusual application URLs aren’t mishandled.

Property Lookup

A bug was fixed such that the IdP’s support for locating additional property files (the idp.additionalProperties and idp.searchForProperties settings) now honors any externally applied values of those properties from the Spring environment, such as the OS environment or Java system properties. Prior to this release, only the values embedded in the idp.properties file were noticed. It is exceedingly unlikely to affect anyone, but in the event you have those properties defined externally, they were not being used and now will be.

New Features

The subject canonicalization feature used after authentication has been redesigned and made simpler to configure when combining multiple login methods in a deployment. New documentation is available in PostLoginCanonicalizationConfiguration. Those with complex c14n setups may wish to review for areas of simplification.

New Objects

New Properties

5.1.4 (March 27, 2025)

This is a patch release addressing an OpenSAML security advisory (TBD) and a number of other outstanding bugs.

Note that the fixes for the advisory included a couple of spurious warnings in the log, as noted above under Known Issues. They appear when processing unsigned requests, and are safely ignorable, they don’t have anything to do with the advisory issues.

Relevant Changes

Those using the CSRF feature and experiencing errors on some browsers (or who did, and then turned the feature off) should note a new option to limit token generation to once per flow conversation, which should be safer to use on more browsers.

Anybody bitten by the problem at startup described in should try this release and let us know if the problem persists, as it contains the only plausible fix we can come up with for what appears to be a complex Java and Spring race condition.

New Properties

idp.csrf.token.perFlow

5.1.3 (July 31, 2024)

This is a patch release containing a number of bug fixes and some library updates. The most significant fix corrects an issue preventing the IdP from applying any defined SameSite policies to the session cookie under certain conditions, which would result in more frequent logins and degrade the SSO experience as compared to V4.


5.1.2 (April 15, 2024)

This is a patch release to address a Spring Framework advisory, a repeat (actually third time) of the same URL parsing bug that resulted in the previous update and impacts the CAS protocol support feature. It also includes an update to the ldaptive LDAP implementation to address a character encoding issue and a fix for an earlier issue around decryption while proxying that was not fully addressed originally.


5.1.1 (March 20, 2024)

This is a patch release that updates Spring Framework to address a security issue that impacts the IdP’s CAS protocol support that was identified the day after the original V5.1.0 release.

This release also fixes a logout regression introduced in V5.1.0 and rolls back the planned warning on the use of hyphens in IdPAttribute names, as this warning occurs under some conditions outside the deployer’s control. It may be re-introduced in the future under more controlled conditions, so use of hyphens remains discouraged.


5.1.0 (March 13, 2024)

This is a minor upgrade containing some new features and some changed defaults (more than are sometimes typical with our minor updates). Please review this information carefully when upgrading.

Changes to Defaults or Behaviors

The following defaults have changed for both new installs and upgrades and should be reviewed for possible incompatibilities:

Other Relevant Changes

The views/logout-complete.vm template was altered (for new installs only) to generalize a “completion” indicator so that the OIDC OP plugin’s upcoming logout support will be automatically compatible with it. In the absence of the change, the plugin’s logout flow will not complete fully in certain cases, though much of the important work will still happen. The change is as follows:

Old logout-complete.vm:
              <!-- If SAML logout, complete the flow by adding a hidden iframe. -->
              #if ( $profileRequestContext.getProfileId().contains("saml2/logout") )
New logout-complete.vm:
              <!-- If required, complete the flow by adding a hidden iframe. -->
              #if (!$logoutContext.flowComplete)

Note that this change will not work on older IdP versions < 5.1 as it relies on an API addition to support the change.

New Features

The limited Content Security Policy (CSP) support in previous versions has been significantly extended to allow more control over the use of Javascript in views. See the UserInterface topic.

The error handling view, when used by the MVC layer outside of Spring Web Flow (e.g., using the back button) has been extended to populate more of the “standard” variables available to the view under other conditions.

Some new variables have been added to the Password login view, see VelocityVariables and a new approach to error message handling in that view is now provided.

Internal support for adding new view rendering technologies at runtime via plugins was introduced, with the first example being Thymeleaf. (We do not have an estimated release date for that plugin as we are so far unable to verify the keys needed to verify the artifacts.)

A feature to add arbitrary request headers to the logging MDC was added. See the LoggingConfiguration topic.

The AACLI tool has a new “unfiltered” option to include unfiltered attributes in the dump.

Transcoding registry service rules now support the use of SAML metadata “tags” to specify overridden names to use when encoding SAML (or other protocol) Attributes into responses. This is an alternative to the use of a relyingParties attribute to limit encoding rules to specific SPs.

Some login flows now provide support for saving a username into a sealed cookie, and recovering the cookie value to pre-populate the username in some cases. Currently this support is limited to the Password flow but may be leveraged by custom flows with additional effort.

A new <EntityRegex> element is supported for defining regular expression-based conditions in several metadata filters.

A new variable, shibboleth.AttributeHelper , is available in some intercept flows and the Hello World flow. It is also available in many error views (where it may be less useful). This provides a simpler means of accessing any resolved attribute values. See VelocityVariablesfor more details.

New Objects

New Properties


5.0.0 (Sep 13th, 2023)

This is the first release of the fifth-generation Identity Provider software. The key documentation links are located on the IDP5 space Home page, such as SystemRequirements, Installation, and Upgrading material. Note the new SystemRequirements as they have substantially changed with regard to Java and servlet container versions.

This release should interoperate with all previous releases of Shibboleth and other software that supports the same standards.

As a major upgrade, the list of issues fixed and features added is numerous. Many significant changes are highlighted below, with particularly noteworthy issues highlighted in note or warning boxes.

There are API additions, changes, and removals, and any third-party extensions will need to be checked for code compatibility and recompiled for use with this version, and any custom scripts created by deployers should be carefully tested and reviewed.

General Notes

Upgrades to V5 and subsequent releases rely on an expanded use of the Module feature to track the configuration files and changes to them. Where previous releases included a copy of the “default” configuration in the dist folder, V5 tracks every user-modifiable file as part of a Module such that new versions of modified files will be created during upgrades. Also a change, the file suffix used will be of the form “.idpnew-majorminorpatch”, including a version suffix allowing identification of the version that created it. As before, if a file is replaced outright for exigent reasons, the old version will have an “.idpsave” extension.

The V5 release includes a significant amount of code refactoring that will impact deployers in largely mechanical ways. That is, where necessary to relocate classes we have provided as much compatibility as we can to support and warn on historical usage, but where post-upgrade changes are mandatory they should largely be “grep, replace” operations changing various class names from A to B.

In most cases, these names may be located in scripts that can be easily adjusted. Those with Java-based customizations will of course need to revise the version(s) of any dependencies to reference to V5 “stack” of libraries and that should flag any incompatibilities. Generally deleting all imports and reimporting the various classes used will be the quickest way to update things.

Notable Class Changes

Old Name

New Name

net.shibboleth.idp.profile.context.RelyingPartyContext

net.shibboleth.profile.context.RelyingPartyContext

net.shibboleth.idp.profile.context.AuditContext

net.shibboleth.profile.context.AuditContext

net.shibboleth.idp.profile.config.SecurityConfiguration

org.opensaml.security.config.SecurityConfiguration

Changes to Defaults

The following defaults have changed for both new installs and upgrades and should be reviewed for possible incompatibilities:

The following defaults have changed for new installs but will not change for properly upgraded systems (generally these are set through explicitly uncommented properties or beans that have to be present to enable a behavior):

Installation and Installation Commands

The following should be noted:

Changes to web.xml

We have heavily revised the content of the deployment descriptor file with an eye on reducing the need for deployers to override it, and reducing future conflicts if it is overridden. Much of the original boilerplate in the file is now gone and the content is now more configurable via Spring (via properties, etc.) and is auto-registering itself at runtime using newer servlet API features.

We have attempted to preserve as much compatibility as possible with V4-compatible versions of the file, but if you have overridden this file via edit-webapp, examining the new version in dist/webapp/WEB-INF/web.xml and modernizing the overridden version (or even better, eliminating it) is strongly encouraged.

Note that it is possible in most servlet containers to override context parameters using special container-specific hooks, usually in the context deployment fragment that specifies the location of the idp.war file. The new version of web.xml contains a few context parameters that can be used to disable the RemoteUser and X509 servlets if they are not in use, and it is advisable to override those parameters using the container rather than by overriding web.xml.

Profile Configuration API Changes

A few properties on the various profile configuration beans used in relying-party.xml have been moved out of some shared interfaces and classes and on to specific instances of these beans where specifically appropriate. We do not expect this to impact deployers. For example, this change makes it impossible to set signAssertions as part of the SAML Logout profile configuration (because there are no assertions to sign). A number of such incongruities were fixed in cases where a property should never have been set due to it being non-functional.

If the system fails to run correctly and indicates the relevant service’s configuration isn’t valid and/or the log is full of issues around the various profile configuration beans in that file, reviewing any unusual settings against the documentation is a good idea.

General Configuration Changes

Prior releases warned, but did not fail, on the presence of dependency or failover elements inside a Static DataConnector. The schema has been updated to actually preclude them since they are unsupported.

Some features in older versions tended to assume the presence of relatively short XML files specific to those features, such as the various <flow>-authn-config.xml files. These files are often now optional and superfluous. In such cases, when a feature no longer relies on any required files, no Module is necessary to create or remove them, and so a number of Modules present in V4 no longer exist in V5, in particular a number of the simpler login flows such as External, RemoteUser, etc. This does not mean the features have been removed or changed, or that existing files won’t continue to work. Generally the specific documentation on a given feature will note that a particular older file may be evaluated for removal.

HttpClient Changes

The Apache HttpClient library has been updated to V5. Most of the changes to this library have been accomodated by our internal Spring declarations and we do not expect most deployers to run into compatibility issues, but testing any custom client definitions is advised. Notably, the deprecated legacy beans that used to be provided for custom client definitions have been removed, per the HttpClientConfiguration documentation.

One breaking change involves HTTP Basic Authentication. While it was possible to make that work in earlier releases, the APIs used do not allow for pre-emptive authentication to avoid extra round trips, which is a fairly major issue with IdP use cases. We have added new APIs and parent beans to facilitate this in a supported and hopefully forwardly-compatible way, per the HttpClientConfiguration documentation.

LDAP Changes

The ldaptive library has been upgraded from V1.3 to V2.x, which relies on an internal LDAP protocol implementation rather than UnboundID (or JNDI) as in older versions.

Note that over the course of the last several releases and particularly during the transition to V4.1, the ldap-authn-config.xml file has become incompatible with the updated implementation and will probably not function properly in an upgraded V5 system. In most cases, simpler uses of LDAP are automatically handled with the modernized ldap.properties and password-authn-config.xml files, and advanced cases can usually be handled in simpler ways, but you are best off starting from scratch in a sense after upgrading and modernizing the relevant files and removing the now-removed one. Members are welcome to ask for help if they have more unusual requirements that can’t be met easily.

Connection Strategy

General improvements have been made to quarantine unresponsive URLs so they are considered inactive for a period before being tried again. Improvements have been made to the ROUND_ROBIN connection strategy to make it stateful and bring it’s behavior inline with user expectations.

Lost Connections

The behavior in V1.3 for lost connections was lazy reinitialization, a connection wasn’t known to be lost until it was used. In V2.x when connections are lost they immediately attempt to reconnect. This feature may produce unwanted noise in logs but is generally beneficial. Note that it can be disabled.

New Properties

Logout Changes

An explicit workaround for Internet Explorer in the reporting of logout status (which itself is not a suggested approach anymore) was removed due to its reliance on an unsupported Java library to detect the browser. Given that IE is no longer supported by Microsoft, we removed the unsupported detection logic.

Removed Features

A number of previously deprecated features, settings, APIs, etc. have been removed. The use of these deprecated bits should have produced a standard warning either at startup or during use in the most recent releases of the software, and most of them are now non-functional or outright breaking. Eliminating warnings before upgrading is strongly advised.

The following non-exhaustive list of previously deprecated features have been removed:

Removed Objects

The following beans are no longer defined, so any references to them will break. Checking your files for them is a good sanity check.

Removed XML Settings

The following settings have been removed from various schemas:

Removed Properties

Newly Deprecated Objects

New Objects

New Properties