The 2.x SP release series guarantees backward compatibility with configuration files from earlier 2.x releases. You can safely assume that anything you tell the SP 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.6.1.4 (Windows Only)

February 26, 2018

This is a service release to provide an updated V1.6.4 of xmltooling that addresses a security issue.

Windows Library Versions

OpenSAML 2.6.1
XMLTooling 1.6.4
Santuario-C 1.7.3.3
Xerces-C 3.1.4
libcurl 7.57.0
OpenSSL 1.0.2m
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.11
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

Shibboleth 2.6.1.3 (Windows Only)

January 12, 2018

This is a service release to provide an updated V1.6.3 of xmltooling that addresses a security issue.

Windows Library Versions

OpenSAML 2.6.1
XMLTooling 1.6.3
Santuario-C 1.7.3.3
Xerces-C 3.1.4
libcurl 7.57.0
OpenSSL 1.0.2m
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.11
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

Shibboleth 2.6.1.2 (Windows Only)

November 30, 2017

This is a service release to provide an updated V7.57.0 of libcurl that addresses a few security issues disclosed this week.

Windows Library Versions

OpenSAML 2.6.1
XMLTooling 1.6.2
Santuario-C 1.7.3.3
Xerces-C 3.1.4
libcurl 7.57.0
OpenSSL 1.0.2m
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.11
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

Shibboleth 2.6.1.1 (Windows Only)

November 16, 2017

This is a service release to provide an updated V1.6.2 of XMLTooling that corrects a regression in background metadata and configuration reloading identified in the V1.6.1 patch version.

Windows Library Versions

OpenSAML 2.6.1
XMLTooling 1.6.2
Santuario-C 1.7.3.3
Xerces-C 3.1.4
libcurl 7.56.1
OpenSSL 1.0.2m
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.11
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

Shibboleth 2.6.1

November 14, 2017

https://issues.shibboleth.net/jira/issues/?filter=12270

Windows Library Versions

OpenSAML 2.6.1
XMLTooling 1.6.1
Santuario-C 1.7.3.3
Xerces-C 3.1.4
libcurl 7.56.1
OpenSSL 1.0.2m
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.11
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

This is a bug fix release primarily in order to correct the security issue with the Dynamic metadata plugin outlined in this advisory.

This release included a regression preventing proper refresh of metadata caused by an unrelated fix in V1.6.1 of the xmltooling library, which was subsequently corrected with the release of V1.6.2 of that library.

Shibboleth 2.6.0.1 (Windows Only)

November 3, 2016

This is a service release to provide updated versions of dependencies. The items in bold have been updated. The primary reason for this update is to incorporate fixes for a number of minor security issues in the updated libraries.

Windows Library Versions

OpenSAML 2.6.0
XMLTooling 1.6.0
Santuario-C 1.7.3.2
Xerces-C 3.1.4
libcurl 7.51.0
OpenSSL 1.0.2j
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.8
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

Shibboleth 2.6.0

June 29, 2016

https://issues.shibboleth.net/jira/issues/?filter=11475

Windows Library Versions

Going forward, we will capture and record the shipped library versions included with the Windows installer, including any service releases.

OpenSAML 2.6.0
XMLTooling 1.6.0
Santuario-C 1.7.3.2
Xerces-C 3.1.4
libcurl 7.49.1
OpenSSL 1.0.2h
log4shib 1.0.9 (erroneously reports itself as 1.0.8, but the file version is correct)
zlib 1.2.8
Boost 1.61 (headers only, no shipped artifacts)
All components built with VC 10

Deprecation of `ignoreCase` / Fix for `<PathRegex>` Security Advisory

This releases provides a permanent fix for the security issue described in this advisory. The nature of the fix is unusual because of the challenging nature of the issue so please read the following, and observe the log output produced.

Across the system, all uses of the ignoreCase property/attribute/setting have been deprecated and replaced by a reversed setting called caseSensitive (with the opposite connotation). Thus, in all cases, using caseSensitive instead of ignoreCase with the value expected will result in correct behavior.

For compatibility, the system will check for the ignoreCase setting and use it if found, but emit a deprecation warning. In any configurations except for the <PathRegex> element, you should replace ignoreCase="true|false" with caseSensitive="false|true" to prevent these warnings.

In the case of the broken setting in the <PathRegex> element, we were forced to account for the workaround that people were advised to use to fix the issue temporarily by reversing the ignoreCase setting. To that end, we have not fixed this setting, but left it broken. If the configuration sees this setting, a louder warning is emitted to note this. The caseSensitive setting that replaces the broken setting has been implemented correctly and so changing to it will address the confusion arising from leaving a broken setting in the configuration and permanently address the problem.

Metadata Backing File Changes

In response to the increasing size of many federation metadata files, and because of a bug in the XML parser used by the software, a couple of significant changes have been made to the metadata processing code.

One change is that the backup copy of the metadata from a remote source is now created by simultaneously writing the backing file to disk while reading it from the source, and only committing the backing file to the permanent file location when successfully processed. This bypasses any bugs in the XML serializer that may cause the data written to be different from the data read, preventing proper signature verification. There are no configuration changes needed and deployers shouldn't see any difference in behavior.

Another change is optional and enables faster startup of the SP's daemon process by skipping signature verification of a backup copy of a remote metadata source. In a lot of cases, starting the SP with a backing file in place causes the SP to check for a change, get back an Unmodified status, and load the backing file. If the backing file is always created by the SP, then its signature will already have been checked, and so you will get faster startup times by telling the Signature MetadataFilter to skip signature verification. To do so, add the setting verifyBackup="false" to the <MetadataFilter type="Signature"> in the configuration.

Blocking DTDs

One of the XML features that's most vulnerable to exploit and the source of a significant number of software vulnerabilities is the DTD feature. SOAP has always disallowed them, and while SAML regretfully did not, in practice most implementations get away with blocking them. The Shibboleth IdP has blocked them for a number of years. The Xerces XML parser used by the SP does not formally support this, but in response to the latest security issue in the parser, the Shibboleth Project team forced a patch into the library to allow DTD support to be turned off using an environment variable.

To make use of this feature, which is strongly advisable, you can set the environment variable XERCES_DISABLE_DTD=1 in the startup scripts for both the shibd and web server processes, or in the Windows system environment. This should always be safe to do, but only works if the Xerces library version is >= 3.1.4 or the patch has been backported.

Conditional Signing/Encryption

A significant enhancement was made to the SP's XML signing and encryption behavior to make it easier to migrate away from the use of TLS client authentication when using SOAP-based profiles. The absence of the signing and encryption settings now implies a new conditional behavior that will work effectively when communicating via SOAP over port 443. This is covered at length in the new wiki topic, NativeSPSigningEncryption. In most cases, the conditional behavior will not result in changes, but it may expose unforeseen (to date) problems with existing IdP metadata that will need to be corrected.

Shibboleth 2.5.5

Partial Integration with systemd

IMPACT: medium

A set of patches and changes to scripts and packaging have been applied to account for the conversion of Red Hat 7, CentOS 7, and SUSE > 12.1 to the systemd framework, replacing the SysV init script model. The reason for making this change in a patch was partly to address existing problems with daemon control on systems that consume large metadata files (i.e., it was already somewhat broken for a lot of people so something needed to be done).

Please be aware that because of limitations in the systemd packaging features of these platforms, the updated package does not have the ability to maintain the "start on boot" status of the shibd service after the upgrade. It should safely restart the service if it's running, but you will need to manually enable the service at a given run level using "systemctl enable shibd" to make sure it starts up after a reboot.

The packages built on systemd-capable images are now built with systemd support that changes the startup model to be compatible with systemd's "notify" feature, allowing the shibd daemon to notify systemd when it has finished loading, and enabling a longer default timeout (90s) for startup to be configured to account for long startup times without introducing delays on other systems. Most deployments should be able to run with the default setting. (A stopgap improvement was made for non-systemd versions, see the separate change noted below.)

Note that the integration with systemd does not extend to the use of socket activation. Sockets are still managed directly by the shibd process.

In accordance with systemd convention, the default control file for shibd can be found in /usr/lib/systemd/system/shibd.service and is a read-only file. Overriding it is done by copying it to /etc/systemd/system/shibd.service and making changes there. Do NOT edit the read-only version as it will be overwritten during updates. In most cases, you won't need to do this.

Because of this change, any existing scripts that reference the old init script may not work and should be adjusted to use the systemctl command or less ideally the /sbin/service command.

Linux Daemon Config Change

IMPACT: low

On non-systemd platforms, a couple of small enhancements have been made to the /etc/sysconfig/shibd file and init script to move a couple of settings into a user-modifiable form. The main such change is the ability to increase the wait time during daemon startup to account for large metadata files that take longer than the default setting to load.

Shibboleth 2.5.4

Red Hat 6 / Cent OS 6 Packaging Change

IMPACT: low

The images used for building the RH6/COS6 packages was fully updated to a recent patch release that includes the update to OpenSSL 1.0.1, so the new builds make use of the newer library. This is noteworthy primarily just so people are aware that they now have this dependency and because they are not usable on older releases of the OS that don't contain that update. You need to be current if you're going to use these packages. The update process should fail if attempted on an older OS.

Web Server Module Logging Change

IMPACT: low

To resolve a number of long-standing issues with log file permissions and log rotation under Unix/Linux from the mod_shib Apache module, the default location for the "native.log" file in RPM installs has been moved to a new directory, /var/log/shibboleth-www. This directory is assigned ownership to the expected Apache user/group accounts on the supported operating systems, typically apache/apache on RedHat flavors and wwwrun/www on SuSE. This should allow initial logfile creation as well as ongoing rotation via the logging library.

Shibboleth 2.5.2

Apache Compatibility Changes

IMPACT: medium

A problem was identified with the use of Shibboleth alongside other authentication and authorization modules in Apache 2.4, because only a single module can "hook" a particular Require rule, such as valid-user or user. The way these rules are implemented made them incompatible with non-Shibboleth use of the same rules elsewhere in a server configuration, such as use of Basic Authentication. It was in retrospect a mistake to support those rules rather than create new rule names specific to Shibboleth.

This has been corrected by defining two new rules, shib-session and shib-user, as replacements. These are always supported on Apache 2.4, and are available on older versions using the ShibCompatWith24 option introduced with Shibboleth 2.5.0 (they can't be supported by default because they could collide with custom attribute rules by those names). Additionally, the ShibCompatValidUser option was added to enable non-Shibboleth use of the original rules with Apache 2.4.

More information about this change can be found in the NativeSPApacheConfig and NativeSPhtaccess topics.

Linux Packaging Change

IMPACT: low

A minor change to the build process for the RPM package sets was made to enable support for GSS-API attribute processing. This functionality is supplied via the MIT Kerberos 5 libraries on the various platforms, and is used by some software projects that make use of Shibboleth. Testing has indicated no problems with this change, and most Apache servers that use mod_ssl already load the same Kerberos libraries anyway.

Shibboleth 2.5.1

Inter-process Communication Changes

IMPACT: medium

Some formats used internally by the software in passing attribute information between processes have changed in order to address bugs. For most deployments, the impact of this is simply that, as always, both web server and the shibd process must be restarted following an upgrade. Normally this is done for you, but should be verified, as this may not always happen when upgrading from older RPM versions.

However, if you rely on remote connectivity to a shared shibd process by multiple front-end web server hosts (i.e., you use a TCP socket connection to other than localhost/127.0.0.1), you will need to take care. Ideally you should upgrade all of the systems at once, but if you wish to attempt a more gradual upgrade, you MUST upgrade all of the front-end systems prior to upgrading and restarting the shibd daemon they are sharing. If one of the systems is co-located with it and cannot be upgraded separately, then it would be the final instance to upgrade. Failure to do this will result in failure to interpret some attribute data generated by the upgraded shibd process.

"Happy Eyeballs" and consistentAddress

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 because of the consistentAddress setting. With this release, the meaning of that setting 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.

Session Cache Initialization

IMPACT: low

By default, the session cache implementation used relies on an implicit in-memory Storage Service. If this is overridden with an explicit reference to an alternate storage implementation, this release now causes SP initialization to fail if that storage instance is not available, since normally SP function will be critically impaired in such a case. This will not affect the vast majority of configurations, including those that rely on in-memory storage of sessions, and has no effect unless an actual initialization problem occurs. It may cause configurations that are actually invalid to fail, although such configurations would have emitted critical warnings in the past.

Shibboleth 2.5.0

Security Algorithm Changes

IMPACT: medium

Recent unpublished attacks have been disclosed that make it unsafe to support a legacy algorithm used by some systems for XML Encryption of SAML assertions. Most IdPs, including all Shibboleth 2.x releases, use a newer algorithm called RSA-OAEP when transporting AES encryption keys. The legacy algorithm is called PKCS 1.5, and is used by some older systems and by some versions of the simpleSAML.php open source product.

We have disabled this algorithm by default, by adding it to a new internal/automatic blacklist of algorithms that we believe should be left off by deployers. Using the internal list means this security improvement is automatic when people upgrade, and allows us to fix future problems in a similar way. We also continue to support explicit/manual whitelisting and blacklisting of algorithms in the security-policy.xml file as before.

To bypass the internal list and re-enable an algorithm, you can set the new includeDefaultBlacklist property in the <AlgorithmBlacklist> element to false, and either create your own blacklist or not as you choose. The log will report which algorithms have been whitelisted or blacklisted by you or by the automatic list during startup.

Option to Limit Redirection

IMPACT: low

V2.4.2 introduced a pair of settings to limit redirections performed by the software. In this release, the settings have been renamed from relayStateLimit and relayStateWhitelist to redirectLimit and redirectWhitelist respectively. The old names are deprecated, but remain supported. In addition, a number of new options for the setting were created to allow for additional control. See the <Sessions> topic for details.

Simplified cookieProps Setting

IMPACT: low

To encourage stronger security posture, warnings have been added when settings related to restricting use to SSL-enabled sites are not active, such as cookieProps and handlerSSL. In addition, the cookieProps setting has been streamlined to support a pair of built-in values, http and https to specify default cookie behavior for both types of sites without having to specify detailed cookie properties. Future releases can then strengthen cookie behavior when warranted without requiring configuration changes.

As part of this set of changes, the default cookie properties now include the HttpOnly flag going forward.

Default Reloading of Attribute Mappings Disabled

IMPACT: medium

A reloadChanges setting of "false" has been added to the default <AttributeExtractor> element that loads the attribute-map.xml file. Issues with the security of the SP can arise if header mappings are changed without restarting the SP, because the set of header names to protect cannot usually be refreshed reliably. To encourage people to restart when changing the mappings, the reload option is turned off.

Reloading is safe, provided that environment variables are used instead of headers (as on Apache by default), or if changes made do not add new header mappings, but the new setting is a safer default.

Logging Defaults

IMPACT: low

The logger properties have been removed from the default configuration file, and the absence of properties now indicates the use of the default logging configuration files (shibd.logger, native.logger). The logging configuration is now set only once, at startup, when these properties are absent.

Windows Installation Changes

IMPACT: low (Windows only)

Substantial changes to non-configuration file locations and installer behavior have been made. See the NativeSPWindowsInstall topic for information. This installer does not support direct upgrading of older releases (as older versions also did not) but this will be the last release with this restriction.

Linux/Unix Installation Changes

IMPACT: high (non-Windows only)

The RPM install now creates a shibd user and group by default and configure the shibd service to run as that user instead of root. File ownership of many of the directories reflects this change, and the standard SP-generated keypair is owned by that user. If you have non-standard credentials in use, or other non-standard installation choices, you may need to manually adjust file ownership or correct minor problems related to this after an upgrade.

An /etc/sysconfig/shibd file is now supported on Linux platforms to override settings in the default init script, and limit the need for editing that file, since upgrades will overwrite it. So far it's primary uses are to override the user account and support the alternate libcurl package on various Linux distributions.

The problems with file permissions preventing creation of the native.log file in the Apache logging directory should be fixed on most typical installations. When default logging configuration files are used (i.e., by omitting logging settings in shibboleth2.xml), the Apache module now establishes the logging configuration ahead of full child initialization, and opens the log file as root. If you supply a logger setting, the log files remain as before and permissions will need to be adjusted.

Files that should persist across server restart have been moved to /var/cache/shibboleth. If you have tools or scripts that take into account all of the directories created or used by the software, please note that addition.

The example style sheet for error templates has been moved to a version-independent location in /usr/share/shibboleth. A logo file is no longer included in the package to avoid accidental use of the Shibboleth logo on production sites. If your existing error templates reference these files, you should correct this by copying files that you need to locations that you control. Never edit files directly in /usr/share.

Apache Changes

For RPM-based installations, the shib.conf Apache configlet that is installed into the OS-designated conf.d directory is now a protected configuration file that will not be overwritten by upgrades. You may safely rely on it if you wish to do so, but it is still suggested that you avoid using it for your own purposes.

Apache 2.4 is supported, but be aware that there are configuration incompatibilities between it and the use of Shibboleth on older versions. Some commands are no longer supported and others are formatted differently, because of changes to Apache authorization APIs. Refer to the documentation for details.

Finally, a change was made to correct a bug. The source code in older versions was such that conditional enabling of commands for the SP module required tests against "mod_apache.cpp", which is obviously not a name that would be unique to this module. The old name was never documented as a stable assumption, so the bug was fixed and the source file changed to "mod_shib.cpp". This is now a guaranteed capability that will not change in the future in a minor upgrade.

Interesting New Features

Post-Login Hooks and Attribute Checking

The SP now supports forwarding clients immediately after session creation to a post-processing hook (see the sessionHook option). A new handler (the Attribute Checker) that works with this mechanism is available that can validate a session against a list of required attributes to perform error handling for missing attributes on behalf of applications with poor SSO integration or error handling.

New Attribute Extractors and Resolvers

New plugins are supplied that can extract well-known information from both assertions and from metadata and create attributes from them. For example, error handling information such as the errorURL attribute or <md:ContactPerson> elements can be extracted, as well as the user-interface extensions. New plugins are also available that transform or copy from existing attributes obtained from an IdP to produce new ones locally.

External Authentication Integration

The SP offers support for integration with authentication mechanisms outside itself, such as local application logins and non-SAML SSO protocols, via a pair of simple interfaces. Complete documentation on this feature can be found in the NativeSPBackDoor topic.

Customizable Audit Logging

The fixed transaction log format has been replaced by a formattable audit log for various events. Details can be found in the expanded NativeSPLogging topic.

Discovery Filtering

The JSON feed generated for consumption by the Embedded Discovery Service can be filtered to include or exclude IdPs on the basis of entityID or "entity attribute" tags. This leaves IdPs available for SSO use, but hides them from user selection. For details, see the reference on the <DiscoveryFilter> element in the NativeSPMetadataProvider topic.

CIDR in Handler Access Controls

Access to controlled endpoints such as the Status handler, and to the shibd daemon, can be limited based on CIDR network ranges. Both IPv4 and IPv6 ranges are supported.

Windows Installation Changes

Not precisely a feature, but important for deployers, are changes to file locations and installer behavior on Windows. Full details can be found in the NativeSPWindowsInstall topic.

Shibboleth 2.4.2

Option to Limit Redirection

IMPACT: low

It was noted in a bug report that the SP allows a malicious attacker to create links that result in arbitrary redirection by the SP after performing activities such as login or logout, by manipulating "target", "RelayState", or "return" parameters provided to various handlers. The SP itself is not at risk as a result, but the opportunity for phishing is increased if a user can be made to interact with a legitimate site and then redirect them elsewhere.

To mitigate this, a new <Sessions> option has been added called relayStateLimit to control which virtual hosts the SP will permit itself to redirect the client to from a handler.

This setting remains off by default, so existing configurations are not affected. This is expected to change in a future release after some experience with it is gained, and deployers are urged to consider trying the exact or host options.

Shibboleth 2.4.0

There are a much larger number of changes than usual because one of the major feature additions for this release is a reduction in the number of required elements, factoring out some configuration material, and some new syntax additions. Many of these changes are labled "high" impact, but this is more from the standpoint of potential impact on support of new installs and of "refreshing" older configurations. All existing configurations should remain valid.

New Default Configuration Files

IMPACT: high

In order to simplify the default configuration for new deployers, the default shibboleth2.xml file is now much shorter and contains few examples of more complex settings. A new example-shibboleth2.xml file is included with the installation with many/most elements included, and illustrating more settings and options that can be copied into the working configuration.

It is suggested that those responsible for supporting large numbers of SPs (either their own, or supporting local deployers) review the new approaches available and consider incorporating them into existing deployment processes. A reworking of local examples and templates is likely to be warranted.

Expanded Use of Defaults

IMPACT: high

A large number of previously required settings and elements have been removed in favor of default behavior for a variety of common cases. These changes are summarized below:

Logging configuration files are now assumed if not overridden.
The <OutOfProcess> element is unneeded unless an extension library is in use.
The <InProcess> element is unneeded for non-IIS use unless an extension library is in use.
The Listener configuration is now defaulted to a Unix domain socket where supported, and a TCP socket on port 1600 of the loopback interface otherwise.
The <StorageService>, <SessionCache>, <ReplayCache>, and <ArtifactMap> configuration is now fully optional and defaults to in-memory (non-clustered) storage.
The XML-based <RequestMapper> is now omitted from default non-Windows installations to encourage use of Apache commands (but can be added back if desired).
The <TrustEngine> configuration is now defaulted to the usual "InlineKey"/"PKIX" chain.
Many default properties that are infrequently or never changed are now removed to reduce clutter, including the signing/encryption flags, default policyId and applicationId properties, handlerURL and assertion export settings, and various settings related to templates.
The historically troublesome acsIndex <SessionInitiator> property is now deprecated, and the system automatically derives a default response endpoint to use based on the protocol.

Simplifying `<ApplicationDefaults>`/`<ApplicationOverride>` Content

IMPACT: medium

Following the initial <Sessions> and <Errors> elements, the remaining content is now unordered, and all legal elements can be intermixed.

Chainable plugins like metadata sources, trust engines, and attribute-related plugins can now be specified without a surrounding Chaining plugin and will be automatically placed into a chain if more than one is specified.

`<Sessions>` Handler Content Radically Simplified

IMPACT: high

A more concise syntax for the majority of content from the <Sessions> element has been added to supplement the original approach of enumerating every handler and endpoint. Many sites will be able to use the new syntax for the majority of needs, possibly supplemented by additional <SessionInitiator> handlers in more advanced cases.

The new syntax relies on a new configuration file, protocols.xml by default, that supplies many of the defaults that were found in the various handler elements, and describes the plugins, low-level bindings, and endpoints that each supported protocol relies on. This file can be extended to describe extensions to accomodate future development without altering the core syntax.

With reference to the new file, basic functionality for Single Sign-On and Logout can be enabled on a protocol by protocol basis using new elements that replace most of the functionality of the <SessionInitiator>, <LogoutInitiator>, <AssertionConsumerService>, <SingleLogoutService>, <ArtifactResolutionService>, and <ManageNameIDService> elements.

Externalization of `<SecurityPolicies>`

IMPACT: low

The content of the <SecurityPolicies> element has been externalized behind a new plugin interface that loads the information from a separate reloadable file, security-policy.xml by default. This information is generally unchanged by most deployers. The actual syntax (and XML namespace) is unchanged, and can be copied to a separate file from existing configurations if desired.

Inheritance of `<RelyingParty>` Settings

IMPACT: low to medium

<RelyingParty> elements specified within the <ApplicationDefaults> element will now be inherited and applied to any overridden applications without needing to be copied.

There is a small chance that this could change the behavior of existing configurations, but this feature is not commonly used, and is more typically meant to apply globally, so these elements are usually duplicated already. The lack of clarity around this behavior, and the need to duplicate settings is enough of a problem to warrant bringing the behavior in line with expectations.

Filtering of eduPersonTargetedID `NameQualifier`/`SPNameQualifier`

IMPACT: low

The default attribute-policy.xml file now includes a filtering rule that requires the NameQualifier/SPNameQualifier values in an eduPersonTargetedID attribute value to match the IdP and SP entityID respectively. This just automates a check that applications were expected to perform if they cared. Existing deployments are not expected to be affected, except in the case of advanced scenarios involving SP "affiliations", in which cases the affiliation ID may need to be added to the filtering rule.

Interesting New Features

Configuration Revamp

While remaining compatible with older configuration files, the format has been substantially revised and simplified. Many elements and settings that were required are now optional/defaulted for the majority of systems, and a streamlined syntax for configuring the endpoints supporting SSO, logout, etc. For more complete information, see NativeSPReleaseNotes.

Enhancements to Remote Metadata and Configuration File Reload / Management

The subsystem responsible for handling remote configuration sources, including metadata, have been rewritten to perform most processing in a background thread to avoid interruptions of service during reloads. Metadata caching has also been enhanced to behave more intelligently and more properly handle the cacheDuration attribute, and metadata is fully filtered, including signature verification, before overwriting backup copies.

All configuration files now support optional signatures which can be verified, to allow for remote distribution of configurations, and support HTTP caching and gzip/deflate compression.

New Cryptographic Features

A new version of XML-Security-C provides support for white/blacklisting algorithms, enabling insecure algorithms to be suppressed without patching the software.

Initial support for Elliptic Curve keys and the ECDSA signing algorithm is nominally supported, though patent issues prevent wide adoption for the foreseeable future. Encryption via ECDH is not yet supported.

Session Cache Improvements

High volume sites can save memory by disabling the caching of SAML assertions. Most sites do not rely on the ability to export assertion access into the application environment, and therefore such caching wastes memory.

Multi-byte Path Support

The supplied NativeSPRequestMapper implementation includes limited support for processing request paths (but not hostnames) as UTF-8. Enabling this option, however, results in case-sensitive comparison of paths, and should only be used with case-sensitive file systems and/or web resources. On Apache, it remains strongly advisable to avoid the XML syntax and rely on native Apache mechanisms.

NameID NameQualifier Filtering

The SP has historically included attribute filtering support for "scoped" attributes, but the filtering of qualifiers on NameID-valued attributes like eduPersonTargetedID was left to the application because in the general case the IdP's name is available to the application to perform a simple equality check. The SP now includes a filter function to do this automatically, and it is enabled by default for the "persistent-id" local attribute.

Shibboleth 2.3.1

Added `matchSubject` `<AttributeResolver>` Property

IMPACT: low to none

A flag is now available to enable SAML "subject matching" when performing queries with the two resolver plugins that utilize the SAML Attribute Query protocol. In previous releases, the Attribute Authority is trusted, based on securely authenticating it, to return an assertion about the intended subject. Enabling the flag enforces an XML comparison between the input subject and the subject of the returned assertion.

This feature is now enabled for simple queries (when attributes are left out of the pushed SSO response) in the default configuration file, but is off by default to ensure compatibility with existing deployments during upgrades.

Shibboleth 2.3.0

Renamed `defaultACSIndex` `<SessionInitiator>` Property

IMPACT: low to none

To align the property names used within the <SessionInitiator> element with the corresponding names of content settings and session creation parameters, the defaultACSIndex property has been renamed to acsIndex. You will see deprecation warnings in the log if the original property is used.

Renamed `scopeDelimeter` `<AttributeDecoder>` Property

IMPACT: low

The spelling of the scopeDelimeter property was inconsistent between the code and the XML schema, was misspelled in the code, and correctly spelled in the schema as scopeDelimiter. Since the code and schema disagreed, and the option was rarely if ever used in practice, a decision was made to change the code to match the schema and the property was renamed to scopeDelimiter. Backward compatibility was not maintained in this instance because the schema itself would not have allowed the older name to validate anyway.

Schema Validation Enabled for Attribute Configuration Files

IMPACT: low

The validate flag was added to the default <AttributeExtractor> and <AttributeFilter> elements to turn on schema validation of the corresponding configuration files. This may catch some errors that would otherwise go unnoticed when changing those files.

Validation of Plugin Content Now Skipped

IMPACT: low

The configuration schema was changed from "lax" to "skip" validation of XML content in most of the plugin-related elements. This partially corrects some unintended conflicts between elements defined in the schema and element names used informally by some of the plugins, which do not typically have schema associated with their internal options. A Xerces bug prevented this problem from affecting the software, but it caused problems with some XML-aware editing tools. Additional changes may occur in future releases to further correct this problem.

There should be generally little or no impact from this change, but a few errors that might have been caught by the XML validator will be caught later in the process and may result in log messages, but not actual failures to start the software.

Interesting New Features

Attribute Value Hashing

The SP now has the ability to post-process any decoded and serialized attribute value by applying a hash function to produce a hex-encoded fixed-length string. This is mainly useful for shortening the length of long identifier formats into a more usable form, but is implemented at the base class level and can be used with any decoder. Refer to the hashAlg property in the NativeSPAttributeDecoder topic.

Shibboleth 2.2.0

Process Behavior of `shibd` on non-Windows

IMPACT: low

At the request of some packagers, a set of patches was accepted to turn the shibd process into a self-backgrounding daemon. This in turn enables more standard integration with packaging and init scripts on certain platforms, but it is a reversal of previous behavior such that by default the process now backgrounds itself instead of running in the foreground.

The init script examples supplied with the software can be used to adjust local copies, or in some cases you can simply remove the '&' character from any scripts that are launching the program. Alternatively you can restore the earlier behavior and avoid making any changes by adding a "-F" option to the command.

Default `acsByIndex` Value

IMPACT: low to none

A change was made to the default value for the acsByIndex SAML2 Session Initiator property. In previous versions, the default value was true, but the stock configuration examples set it to false. With this release, the setting has been removed from the examples and the default value reversed.

This is being changed in response to a number of problematic issues surrounding the use of the feature, which causes the <samlp:AuthnRequest> message to carry the SP's desired response location by reference to metadata instead of by value. Other than message size, there's no advantage to using the feature, so to reduce the likelihood of problems going forward the option is now invisibly disabled by default.

Change to `<Policy>` Schema

IMPACT: low

A conflict was identified in the older schema for the <Policy> element that contains the security rules to evaluate messages and assertions against. To correct the problem, the repeating child element was renamed from <Rule> to <PolicyRule>.

Taking advantage of this change, the 2.2 SP uses the particular child element used to determine how to process the associated policy:

If the older <Rule> syntax is used, the software emits a warning, and also automatically installs a rule of type="Conditions" using the default options for that rule (refer to the NativeSPPolicyRule topic for those defaults). This results in behavior equivalent to the older SP's processing rules.

If the updated syntax is used, the software processes the rules exactly as specified, with no implied behavior. Enforcing SAML conditions is therefore explicitly a function of configuring that policy rule, rather than being assumed. This allows other condition types to be processed in a pluggable fashion, including the new support for delegation.

Deprecation of `<saml:Audience>` as Top-Level Element

IMPACT: low to none

The use of <saml:Audience> elements within an application configuration element is now deprecated in favor of specifying additional audience values directly within a policy rule of type="Audience".

Top-level elements are still manually processed, but result in a deprecation warning.

This feature is rarely used, and even more rarely needed. If you rely on this extension, it's suggested that you contact the support list for assistance in correcting whatever problem led you to rely on it.

Interesting New Features

Dynamic Credential Reloading

The SP now has the ability to detect local changes to private keys, certificates, and CRLs, or to fetch and cache them from a remote URL and reload them at intervals. Obviously remote access is mostly designed for use with CRLs, which in turn are typically used when verifying signed metadata.

Delegation Support

The SP includes bug fixes and feature additions to provide support for the SAML Enhanced Client/Proxy Profile and the adaptation of it used to implement delegated authentication from users to services in an n-tier fashion. The only current description of the approach is here, but more deployer-oriented material will be forthcoming.

By default, the SP will not allow delegated access by services unless specific changes to the configuration are made, and you can implement a variety of basic policies over the delegation to permit.

Attribute Decoder Additions

Some additional decoder plugins are now available to support more advanced kinds of SAML attributes. This includes support for public keys and certificates within attributes, as well as processing rich XML values either directly or by extracting portions of the XML.

Metadata "Tag" Consumption

The SP includes support for extracting SAML attributes attached to SAML metadata entities via the <EntityAttributes> SAML extension. This allows for so-called "meta-tags" about IdPs to be expressed to applications. Attributes can be packaged into SAML assertions and signed by third parties, and these can be processed in highly customizable fashion.

An example scenario that is oft-discussed is the ability for federations to express the "levels of assurance" that a particular IdP is authorized to assert for its users, and the SP can now enforce such a restriction programmatically by limiting access or filtering user attributes based on the "tags" found in metadata.

"Simple" Attribute Aggregation

As a placeholder until more advanced approaches are agreed to, the SP includes a resolver plugin that can perform SAML queries against third-party Attribute Authorities based on identifiers or attributes supplied by the authenticating IdP. This allows queries for additional data to be performed and the results combined with the original data, as long as a common (and non-secret) identifier is shared by the data sources for the user. In addition, the security for this query is limited to authenticating the SP directly and is not based on temporal considerations such as the user's presence.

The pointers to additional authorities can be hardcoded into the configuration (i.e. well-defined data sources) or passed by reference from the authenticating IdP in a SAML attribute as a dynamic referral.

Advanced Metadata Signature Processing

Fixes to various bugs and enhancements to the file-based CredentialResolver make it possible to apply more advanced trust models to the verification of metadata signing keys. It is now at least somewhat practical to implement traditional certificate validation of metadata signing certificates, including the incorporation of dynamically-obtained CRLs. This limits the need to pre-distribute signing keys ahead of time.

Form POST Preservation across SSO (Apache Only)

For Apache servers only, the SP can be configured to cache form parameters supplied during a request for a protected resource (when no session is active) and instruct the client to "replay" them following a successful SSO response as though the session were in place. This is a feature of some other SSO packages and has been attempted in the SP for the first time. The replay mechanism involves a JavaScript-decorated form template populated with the original data.