Please review these release notes before upgrading your system. You should review all the versions subsequent to the one you're running prior to upgrade.

3.1.0.1 (April 14, 2020)

The version of the Windows installer was bumped to 3.1.0.1 to correct an issue with the initial installer and matches the code in the 3.1.0 release.

3.1.0 (April 13, 2020)

This is a minor update that includes a number of new features and bug fixes.

SameSite

The most significant changes are additional settings and default behavior to accomodate the Google-imposed SameSite cookie change. By default, the SP now assigns SameSite=None automatically to a subset of the cookies it may create that are explicitly only usable in a cross-site context, such as cookie-based RelayState or POST recovery features. It can optionally adjust the SameSite attribute for the session cookies it creates as well, using the new sameSiteSession property, but defaults to leaving session cookies unmarked and subject to default browser handling.

The changes described above by default will degrade functionality for older Safari versions on macOS and iOS due to a bug Apple refused to backport a fix for. A workaround is provided to accomodate broken clients but is left off by default to avoid a permanent state of legacy compatibility, but can be enabled via the sameSiteFallback setting in the <Sessions> element in the configuration. It is safe to enable, but it is recommended that once support for older, broken clients is no longer a priority that the setting be removed.

CSRF Protection

Another significant feature addition is a cookie-based request/response correlation feature that is designed to enable deployers to block unsolicited SSO responses if they choose to do so. This "standard" and very common SAML feature is actually a CSRF vulnerability by design. There is no practical value to correlating messages except to enable blocking unsolicited responses, so the two features go hand in hand. It is also very fragile because of the necessity of relying on cookies when hostnames don't match (e.g., starting a request on one hostname and delivering a response to another). For more information on this feature, see CSRF.

Other Hardening

Additional changes have been appllied to the default configuration (NOT upgrades) to harden the redirection behavior of the system to limit the use of the SP as an open redirector. A limitRedirects setting of exact has been added to the <Sessions> element.

Attribute Filtering Changes

A serious attempt has been made to align the schema and supported plugins with the recent releases of the IdP software to the extent practical. This particularly includes deprecating the basic and saml extension schemas, as was done previously in the IdP, and adding a set of types to the base schema that match the equivalent functions supported by the IdP, along with a few that are specific to the SP. The extension schema support will be removed from a future version of the SP. Most filter policies in the SP are minimal, so the changes needed are equally minimal.

Updated documentation on which features are supported along with links to the IdP documentation are found in XMLAttributeFilter.

Metadata Performance

A note regarding performance on large metadata files: Testing on a 2 year old laptop running Windows 10 with 16GB of RAM against a metadata file of roughly 70M in size, with signature checking, post-processing, and a lot of log output (the latter two adding substantial overhead), complete processing time was about 3 minutes. If you're seeing results significantly worse than this, you are either badly underresourced in CPU or RAM or are using out-of-date XML libraries that may have been unwittingly improved in ways we haven't identified.

Configuration Schema Improvements

The XML Schema for the core configuration was tightened to properly reject content such as empty XML Attributes. This was leading to crashes in some cases instead of being caught properly at startup. Some invalid configurations may have accidentally loaded successfully in prior versions but will be properly caught as invalid now.

3.0.4 (March 11, 2019)

A patch has been released to fix a number of minor issues and to address a security issue.

3.0.3 (December 19, 2018)

A patch has been released to fix a few more minor issues and to address a security issue.

3.0.2 (August 2, 2018)

A second patch has been released to fix a few more minor issues and a major bug in the new IIS module that prevented its use in some significant cases.

This patch also prevents some of the unintentional changes to the attribute-map.xml and attribute-policy.xml files during RPM upgrades in cases where the original files hadn't been modified. The files will still be replaced but the removed mappings are historical and deprecated and this is outlined down in the main 3.0.0 section and in the upgrade material.

Finally, the Windows installer includes an update to the xml-security-c library to 2.0.1.

3.0.1 (July 18, 2018)

A patch has been released to address a couple of serious regressions and a few minor nits. The xmltooling library was also updated to 3.0.1 as part of this release, and subsequently to 3.0.2 to correct a linking issue in the makefiles on non-Windows platforms.

3.0.0 (July 17, 2018)

This is the first release of the third-generation Service Provider software. The key documentation links are located on the SP3 space Home page, such as System Requirements, Installation, and Upgrading material.

This release interoperates with all previous releases of Shibboleth and other software that supports the same standards. While this is a major upgrade, that primarily reflects changes to the internals, which do not in general impact deployers. It is a fundamentally backward-compatible release that introduces new options but fully supports the V2 configuration format and makes relatively few changes to existing system behavior.

It is designed to be applied as an upgrade directly to existing systems, and while we strongly advise testing in a non-production environment, the majority of deployments should operate successfully following an upgrade with little or no effort.

Significant Behavioral Changes

Absent explicit configuration, the default digest algorithm used when creating signed messages has been updated from SHA-1 to SHA-256, reflecting industry guidance and matching the IdP V3 default. If compatibility with older systems is required, the default algorithm can be explicitly set via the  <ApplicationDefaults> element, or specific rules for those IdPs may be specified via <RelyingParty> overrides. Note that in the majority of deployments, SPs rarely sign (and rarely need to sign) anything except for SAML logout messages.

The new software has an attribute-map.xml file that removes the older, incorrect form of the eduPersonTargetedID attribute from the file, and the strongly discouraged "unscoped" form of eduPersonAffiliation. In RPM installs, this file will overwrite the older default file if it hasn't been modified by the deployer, so this can result in changed behavior unless the file is restored. If you want to prevent this, a simple edit to that file (add a comment) will do the trick, and the old file is available under a different name in any case.

For macOS systems, Apple has deprecated their Apache software and the SP "port" is now built against the apache2 port, which affects port upgrades. The module built by the upgraded port may not function in the Apple Apache software and is not meant to be used with it.

Finally, be aware that RPMs are not going to be officially available for a handful of older/unsupported OS versions, including RHEL 5, SUSE 10, and some older SUSE 11 versions. CentOS 5, while unsupported, continues to have a package stream available, which should work for RHEL 5.

Changed Defaults

Excepting as noted above, most actual underlying system defaults have remained unchanged but there have been changes to the default configuration files included with new installations, and some defaults have been adjusted when the system detects that the configuration is not a legacy one.

Instead of generating a single key pair, new installs will have two key pairs generated, one for signing and one for encryption. Some SPs do not need a signing key, but all SPs should support encryption, so this isolates the more-used key from the lesser-used key, and improves the overall hygiene of the system by keeping keys used for different purposes separate. Upgrades of existing systems will leave the original key untouched and continue to operate with a single key for both.

The default configuration specifies a more restrictive and secure set of TLS ciphers to support when contacting other systems. This can be changed if interoperability is impacted.

SAML 1.1 support is not enabled by default; add back the string "SAML1" inside the <SSO> element to enable it.

Support for Attribute Queries is not enabled by default to eliminate a common source of confusion. This will impact behavior when interacting with out of date Shibboleth IdPs relying on SAML 1.1 without pushed attributes. Such systems should be migrated to SAML 2.0, but query support can be re-enabled if necessary by adding <AttributeResolver type="Query" subjectMatch="true"/> to the <ApplicationDefaults> element.

The default <TrustEngine> configuration (when nothing is specified, as in most cases) is now ExplicitKey-only and does not enable PKIX support.

New Windows installs default to use of a new IIS7+ native module instead of the older ISAPI module, which includes some functional differences that, while much safer, may impact application code.

Logs from the web server modules (the so called "native" log) now default to local syslog or the Windows Event Log, rather than a file. This eliminates a huge source of file handle leaks and permission problems that have plagued the software. The default logging level has also been adjusted to WARN.

The format of the transaction log has been updated to something more useful and parseable.

The attribute mapping rules and priority for populating REMOTE_USER have been refreshed to reflect modern (and post-modern utopian) practices.

In addition to these changes, some settings have different default settings based on whether the configuration file is an upgraded V2 file or a newly installed V3 file, based on the XML namespace of the file (further explained below).

Configuration Format and Compatibility

To maintain appropriate behavior during upgrades, the name of the default configuration file remains shibboleth2.xml, despite the possible confusion this may create. However, the XML namespace has been "forked" to create a new configuration format that allows the software to easily detect whether it should operate in a legacy or updated manner in a few cases.

The old namespace is/was urn:mace:shibboleth:2.0:native:sp:config and the schema supported in V2.6 has been included.

The new namespace, which is used by default, is urn:mace:shibboleth:3.0:native:sp:config and its schema includes both some new settings and omits a number of deprecated settings.

Thus, it is a relatively simple matter to "upgrade" one's configuration:

  1. With the original configuration, verify a working system, and check the log(s) for any DEPRECATED warnings.
  2. Fix any settings causing those warnings until they're gone.
  3. Update the namespace at the top of the file.
  4. Restart, test, and fix any straggling errors.

Most of the changed defaults noted above will not apply to such a migrated system since they depend on actual changes to the configuration, and the vast majority of deployments can simply do a bit of testing, make the bump, and be good to go.

Deprecated Settings

Some syntax has been deprecated in V3. As a rule of thumb, if something is documented in this SP3 wiki space, then it is not deprecated. Otherwise a warning will usually be found in the log when the original configuration is used, and an error may occur if the configuration namespace is bumped.

Time permitting, a summary of deprecated options will be provided here.

Significant New Functionality

IIS7

A new IIS plugin is available for recent (IIS7+) versions of IIS. This is a significant improvement on the older module:

Stateless Clustering

A form of session recovery across clustered SP nodes using encrypted cookies is available. While making clustering much simpler, it does affect the behavior of logout in some cases, but it offers more flexibility for deployers willing to make trade-offs.

Simplified Virtual Hosting Support

A set of virtual hosts can be auto-assigned a distinct entityID without the creation of <ApplicationOverride> elements to do so, using the new entityIDSelf content setting. While this does not eliminate the overhead of managing metadata for each host, it does eliminate most actual configuration overhead within the SP itself.

In addition, when overrides are still required for other purposes, it is now possible to load XML fragment files containing just the override configurations from a directory at runtime, including adding additional overrides on the fly without configuration reload.

Dynamic Metadata

The Dynamic metadata providers have been enhanced along with many bugs fixed, to match and in some cases surpass the features available with the Identity Provider, including simpler support for MDQ-capable federation servers, local file-based lookup via hash, and greatly enhanced caching and robustness features.

Administrative Logout

An endpoint is available to programmatically remove sessions based on the SP-assigned session ID, with associated communication to an IdP via SOAP where possible (though this is rarely possible). While complex, it is possible to create a more limited shared store of revoked sessions that prevents the stateless session recovery feature from re-creating the session in some cases, without requiring a fully-shared session store.