The 2.x IdP release series guarantees backward compatibility with configuration files from earlier 2.x releases. You can safely assume that anything you tell the IdP to do in one release should result in the same essential behavior in a future upgrade.

However, it is possible for newer releases to introduce changes that deprecate older configuration options or formats, and you are encouraged to review this page for any changes required to "modernize" your configuration after an upgrade to make production support simpler, and future upgrades smoother. Some new features may also depend on making these changes.

Shibboleth 2.4.3 Configuration Changes

The following represent new default settings and other significant configuration changes made since the 2.4.2 release.

Elimination of Xerces-J and Xalan Dependencies

IMPACT: high

This release addresses a denial of service issue present in the Xerces parser that has been a required component of the software for most of its history. The 2.4.3 distribution no longer includes any special XML libraries and eliminates the requirement to endorse those jars to override the Java-supplied JAXP implementation. In conjunction with this, the internal.xml configuration file has changed to install a parser SecurityManager compatible only with the standard Oracle-supplied JAXP layer, reflecting the fact that there is no portable way to install a SecurityManager into the JAXP parser implementation and the Oracle JDK/JRE is the only officially supported option.

The first line of defense against the denial of service issue is to prevent large POST bodies from being accepted, as outlined in the advisory text. This should be done immediately and can be done independently of any other fix.

A secondary task for older installations is to unendorse the Xerces and Xalan libraries from your container, remove the libraries from their endorsed location, and lastly, modify the internal.xml file as described in the advisory. The latter change is not optional, and will guarantee that the Oracle-supplied parser is used. The IdP will fail to load if this change is not done, and conversely, the IdP will also fail to load if the file is changed but the endorsement is not undone.

Lastly, if you choose to use an unsupported Java implementation, you will need to change the file to either remove the SecurityManager property from the ParserPool bean, or change the class to the correct value for that unsupported JAXP parser.

Shibboleth 2.4.1 Configuration Changes

The following represent new default settings and other significant configuration changes made since the 2.4.0 release.

Hostname Verification on Configuration Retrieval

IMPACT: high

This release corrects a bug similar to the one discovered in metadata retrieval noted below for 2.4.0, but that applies to the use of the HttpResource and FileBackedHttpResource types when used for remote access to configuration files (in service.xml) or with a ResourceBackedMetadataPovider in (relying-party.xml). This patch release enables hostname verification, prpvided that the disregardSslCertificate option is not enabled for metadata use, which as noted below, globally applies. In such cases, you should reconsider use of a remote access strategy for configuration files, or use a separate cron task to download updated files using a tool that does enforce proper checking.

SVN Support Now Requires Separate Download

IMPACT: high

After review, the project has determined that we are unable to distribute TMate's SVNKit software library, and have therefore been forced to remove it from the Shibboleth IdP distribution. As a result, deployers relying on the SVNResource type for access to configuration files (in service.xml) or with a ResourceBackedMetadataPovider in (relying-party.xml) cannot upgrade to this release without taking the additional step of downloading and adding the svnkit jars to the lib directory in the unpacked distribution before running the installation/upgrade script. The library and its dependencies can be obtained directly from http://svnkit.com/. Note that the latest versions are compatible only with newer subversion working copy formats and existing deployments may need to use the older 1.3 release that had been shipped with the software in the past, or update/remove their current working copies. We have not tested on anything past 1.3.

Shibboleth 2.4.0 Configuration Changes

The following represent new default settings and other significant configuration changes made since the 2.3.8 release.

Hostname Verification on Metadata Retrieval

IMPACT: high

Due to a bug in the Apache Commons HTTP client used by the IdP, previous versions do not perform hostname checks against the certificate presented by the server when retrieving metadata from remote locations over https. (It's also possible to configure other configuration files as remote resources, but this is not typical.) In fixing this bug, existing metadata sources may fail if the server certificates used by the metadata host are not correctly named. When using signed metadata, this may be irrelevant, in which case you can use the disregardSslCertificate option to turn off this verification. Note that this must be set uniformly for all metadata providers, due to an additional limitation in the HTTP client.

Updated Dependencies

IMPACT: low

Many of the Java dependencies in the software have been upgraded with this release, some of them for the first time in a while. While we have tested our own use of these libraries, some of them are used by third-party extensions or local customizations, such as the Velocity macro template engine and the logging libraries. You should test any of these dependencies in your own software before upgrading to ensure you aren't affected by these changes.

"Happy Eyeballs"

IMPACT: low

Mixed IPv4/IPv6 deployments may be affected by the co-called Happy Eyeballs algorithm that causes the HTTP connection to bounce randomly between the two protocols, resulting in the client address changing. In prior releases, this would result in session invalidation by default. With this release, the enforcement of address checking has been expanded to support mixed deployments by storing both types of client addresses for a single session. The first time a request with a particular address type is seen, the session is "locked" to that address. Across upgrades, existing sessions will be invalidated due to the change in format (in other words, users will have to login again).

Example Login Page Changes

IMPACT: low

The example login.jsp template has been modified to support more responsive design for use with mobile devices. This is primarily to simplify the example page, and provide a starting point for newer deployers that may be more useful. The original example page has been preserved and is found in the files nonresp-login.jsp and nonresp-login.css. None of these changes should affect upgrades, which should control the templates used for the UI.

IMPACT: medium

A change was made to detect an error arising when the client fails to supply a session cookie back to the IdP after the authentication process completes but before issuing a SAML response to an SP. In past versions, a failure to check for this condition resulted in the IdP issuing "empty" SAML assertions to the SP. This has been fixed in order to prevent such a response, and if the session cannot be identified at the appropriate time, an error is returned indicating this. When repeatable, usually this is a sign of a cookie exhaustion issue in the client, and clearing the browser's cookie cache may resolve the problem. Deployers should be aware of this new error condition in case they receive questions about it. The specific message is "Authentication failure, session missing during completion of profile handler". This is also logged as a warning.

Velocity StringResourceLoader

IMPACT: low

Older versions of Velocity included with the IdP prior to this release required a custom extension installed into the Velocity engine. With the update to Velocity included in this release, the custom extension is no longer necessary, but is supported for backward compatibility. To adjust your configuration to reflect this, you may wish to modify a line in internal.xml containing the string edu.internet2.middleware.shibboleth.common.util.StringResourceLoader and change it to org.apache.velocity.runtime.resource.loader.StringResourceLoader, as you will see in the most recent version of the file.