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.0.0 (XX XX, 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.
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.
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. Most SPs do not need a signing key, but all SPs should support encryption, so this isolates the important key from the lesser-used key, and improves the overall hygiene of the system by keeping keys used for different purposes separate.
- 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.
- 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.
- The default
<TrustEngine>configuration 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 fules 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).
cacheAssertionsdefault 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 at first. 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 simply by updating the namespace at the top of the file, restarting, and fixing any errors that are reported, typically a very small number. Most of the changed defaults noted above will not apply to such a migrated system and the vast majority of deployments can simply make the bump, do a bit of testing, and be good to go.
Some syntax has been deprecated in V3. As a rule of thumb, if something is documented inthen it is not deprecated. Otherwise a warning will usually be found in the log if 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
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 onpresentation of attributes, which eliminates a range of concerns and preventative overhead regarding header spoofing/smuggling. for the
- It is significantly easier and less error prone to integrate into IIS.
- It supports the optional preservervation of post data.
- It supports REMOTE_USER properly, and can be configured to support native IIS Role-based Authorization.
A form of session-migration 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. 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.
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.
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.