ReleaseNotes

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.

Known Issues

None at this time.

3.4.1.4 (October 11, 2023)

A new version of the Windows installer was released updating libcurl to 8.4.0 to address a security issue and to ensure that a more modern curl version has been shipped in case of future vulnerabilities. Other than rebuilding dependent libraries to accomodate a DLL name change, no other changes were made.

3.4.1.3 (June 12, 2023)

A new version of the Windows installer was released updating xmltooling to 3.2.4 to address a security issue. OpenSSL was also updated to 3.0.9 and a bug preventing optimized reloading of metadata via HTTP/2 was also fixed.

3.4.1.2 (March 13, 2023)

A new version of the Windows installer was released updating zlib to 1.2.13 to address a security issue. The version of libcurl was also updated to 7.88.1 in the process.

The installer was also patched to avoid overwriting file system ACLs on upgrades.

3.4.1.1 (February 8, 2023)

A new version of the Windows installer was released updating OpenSSL to 3.0.8 to address multiple security issues. The version of libcurl was also updated to 7.87.0 since it had to be rebuilt anyway.

As a general piece of advice, OpenSSL continues to be endemically impacted by bugs around their support of the hopelessly convoluted PKIX specification, and SPs should be configured whereever possible to bar the use of this code by turning off the PKIX TrustEngine. Because the V3 SP defaults to including support for PKIX by default when no <TrustEngine> element is present in the configuration, it is a good idea to explicitly configure a single engine by adding this line somewhere inside the <ApplicationDefaults> element (if no other such element is present):

Note that enabling PKIX support does not inherently even allow for evaluation of certificates anyway. Using that feature requires extensions to SAML metadata to carry trust anchors that are very likely not present in any metadata seen in the wild.

3.4.1 (January 10, 2023)

This is a small patch to address a few bugs, in particular:

• Reinforcing the xmltooling library (V3.2.3, included in this Windows release) to block an unnecessary XML Encryption construct, related to the advisory issued for the IdP recently. The SP is not believed to be vulnerable, but this is a defensive measure.

• Adjusting the default ACL on Windows when the SP is installed outside of “Program Files” to prevent open write access to the folders. Note that with the huge variety of IIS security configurations, you may need to further adjust ACLs if unexpected user accounts are being used by IIS, so test before use. We will revert this change if people encounter problems, and you MUST take responsibility yourself for any ACL rules on your own servers; do not rely on us to get this right for you.

• A warning has been added to the log when systems do not configure an explicit value for the redirectLimit setting. The default for this setting remains liberal for compatibility, so the warning was requested to highlight that fact.

3.4.0 (November 3, 2022)

This is a minor update containing a new setting suggested by a contributor (thus the unplanned minor version change) controlling retries when TCP connections to shibd are used. The other changes are minimal in nature.

The Windows package contains refreshed libraries, including precautionary security updates for OpenSSL and libcurl.

TLS Renegotiation Change on Windows

Because of the update to OpenSSL on Windows, there is an inadvertent change to the default behavior of the software when interacting with sources of metadata of IdP SOAP endpoints that do not support secure TLS renegotiation. This was permitted by default before and now is not. Should this be a requirement, it is possible to leverage the <TransportOption> element (either globally or in a specific <MetadataProvider> to re-enable the option for this (see OpenSSLTransportOptions).

3.3.0 (November 30, 2021)

This is a minor update that contains a small number of fixes, one small feature addition, and a number of additional deprecation warnings for at risk features. This version also introduces changes to the supported platforms and to the packaging process.

This is expected to be the final feature update to the SP in its current form with the project’s focus shifting to radical redesign.

Deprecations

Deprecations are now handled with a common “Shibboleth.DEPRECATION” logging category for easier identification.

While deprecating a feature does not guarantee it will be removed and not deprecating something does not guarantee its continued support, we have tried to identify the most likely features that are at risk during the redesign process that will occur before a V4 is available.

Platform Support

macOS is now an unofficial platform and the macport of the SP will be maintained only on a voluntary basis.

Support for SUSE is now partial and limited to members only, and we encourage the use of the official packages that are included with it.

Official support and packages will now be provided for Rocky Linux 8 and Amazon Linux 2.

Support for CentOS 8 will officially cease with the approaching end of that platform’s fixed release cadence at the end of 2021. We would suggest moving to Rocky Linux 8 instead if you need a free equivalent, though we will likely continue to provide CentOS 8 packages if we can, and the Rocky packages will most likely work on it anyway.

RPM Packaging

The RPMs are no longer produced online by the OpenSUSE Build Service but using a local, Docker-based process. This is a much faster process for us but it expands and constrains what we can support at the same time. As a result, a number of older platforms for which we have been unofficially producing packages but not supporting for some years will not see further package updates starting with this release. We have no plans to remove those older packages from the mirrors.

3.2.3.1 (August 2, 2021)

A new version of the Windows installer was released to patch a couple of minor issues and regressions within the IIS module.

3.2.3 (July 6, 2021)

This is a patch update that fixes a regression in the RequestMap implementation introduced in V3.2.0. Earlier versions are not impacted by this bug but are of course subject to critical vulnerabilities so this is now the only safe version to use.

3.2.2.2 (June 22, 2021)

A new version of the Windows installer was released updating the IIS module to correct a critical security vulnerability.

All WIndows deployers on IIS should review the advisory and should update to this release at the earliest opportunity.

Note that in fixing this bug in the SP, a very serious vulnerability in Microsoft’s Default Document module was exposed that causes cross-contamination of requests, where a previous request’s internal state affects the state of the following request for the default document. This manifests by exposing duplicated attribute data because the SP is appending one copy of the data to a previous copy it created already.

This can be worked around in most cases by setting exportDuplicateValues="false" for the affected content, but some duplicated data from the built-in variables set by the SP still exist even with this option.

3.2.2.1 (May 26, 2021)

A new version of the Windows installer was released updating libcurl to the latest releases to address a security advisory fixed in curl 7.77.0.

3.2.2 (April 25, 2021)

This is a patch update that fixes a couple of bugs and addresses the security vulnerability described in this advisory.

3.2.1.1 (April 6, 2021)

A new version of the Windows installer was released updating OpenSSL and libcurl to the latest releases to address non-impactful security advisories associated with those updates.

3.2.1 (March 16, 2021)

This is a patch update that fixes a couple of bugs and addresses the security vulnerability described in this advisory.

3.2.0 (December 14, 2020)

This is a minor update that includes some minimal new functionality and addresses some bugs.

Changes to Defaults

The shipped default for the handlerSSL and cookieProps settings (see Sessions) is now to assume use of TLS because of the problems combining use of insecure cookies with SameSite. Upgrades are not impacted by this change, but all deployments will encounter problems going forward without TLS due to browser changes.

A few configuration settings have been renamed as part of the project's broader push to eliminate insensitive language from the code and some new deprecation warnings may be observed.

3.1.0.2 (August 31, 2020)

A new version of the Windows installer was released containing a Windows-only fix to the IIS module to address a security issue.

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.

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 redirectLimit 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).

• The cacheAssertions default in the StorageServiceSessionCache has changed from true to false when the V3 namespace is used.

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.

• Various plugins relying on external XML files or resources used to support a number of equivalent settings (e.g., file, uri) for specifying the local or remote resource, and these have been eliminated, with only path and url remaining. Sometimes the error messages can be obscure if you don't fix these up, but the warnings are clear when the V2 namespace is used, so always review those first.

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:

• It supports Server Variables rather than relying on HTTP Headers for the presentation of attributes, which eliminates a range of concerns and preventative overhead regarding header spoofing/smuggling.

• It is significantly easier and less error prone to integrate into IIS.

• It supports the optional preservation of post data.

• It supports REMOTE_USER properly, and can be configured to support native IIS Role-based Authorization.

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.