The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 wiki space for current documentation on the supported version.
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.
Also be aware of the following issues regarding container or Java compatibility:
- 1 4.0.0 and Later
- 2 3.4.8 (Dec 17, 2020)
- 3 3.4.7.1 (July 22, 2020)
- 4 3.4.7 (July 1, 2020)
- 5 3.4.6 (Oct 2, 2019)
- 6 3.4.5 (Sep 18, 2019)
- 7 3.4.4 (May 1, 2019)
- 8 3.4.3 (January 9, 2019)
- 9 3.4.2 (December 19, 2018)
- 10 3.4.1 (November 1, 2018)
- 11 3.4.0 (October 10, 2018)
- 12 3.3.3.1 (June 27, 2018) (Windows Only)
- 13 3.3.3 (May 16th, 2018)
- 14 3.3.2 (October 4, 2017)
- 15 3.3.1.1 (March 23, 2017) (Windows Only)
- 16 3.3.1 (March 15, 2017)
- 17 3.3.0 (November 10, 2016)
- 18 3.2.1.1 (June 23, 2016) (Windows Only)
- 19 3.2.1 (December 19, 2015)
- 19.1 Important Notes for Upgraders
- 19.2 New Objects
- 20 3.2.0 (November 18, 2015)
- 20.1 Important Notes for Upgraders
- 20.2 New Objects
- 20.3 New Features
- 20.4 Miscellaneous Fixes
- 21 3.1.2 (July 1, 2015)
- 22 3.1.1.2 (Mar 31, 2015) (Windows Only)
- 23 3.1.1 (Mar 26, 2015)
- 24 3.1.0 (Mar 10, 2015)
- 24.1 Important Notes for Upgraders
- 24.2 New Objects
- 24.3 Miscellaneous Fixes
- 25 3.0.0.11 (Feb 25, 2015) (Windows Only)
- 26 3.0.0 (Dec 22, 2014)
4.0.0 and Later
See ReleaseNotes for information on the new major branch of releases.
3.4.8 (Dec 17, 2020)
This is the final patch release of the V3 branch of the IdP in order to "finalize" the set of library dependencies included to the most current set practical as a final roll up for this branch. Those likely to be operating this branch beyond the end-of-life date approaching should consider using this version to be as current as possible.
3.4.7.1 (July 22, 2020)
This is a service release of the Windows installation package in order to address a security issue in Jetty, which has been updated to version 9.4.30. It is unneeded by anyone maintaining their own Java container, which continues to be strongly recommended.
3.4.7 (July 1, 2020)
Getting issues...
This is a patch update containining a few bug fixes and an updated version of the Jackson JSON parser to address some security issues. While the IdP is not believed to be vulnerable to the issues, the update was done out of an abundance of caution.
3.4.6 (Oct 2, 2019)
Getting issues...
This is a patch update containing some memory-related bug fixes, and addresses a security advisory involving the use of the External, RemoteUser, X509, and SPNEGO login flows.
Fixing the security issue required an internal redesign of the External login flow (the other three essentially reuse the External flow to function) and the fix required changes to some Java classes that are part of the public API. This is allowed in a patch when necessary to address critical bugs. While these changes are visible, they do not impact the documented/intended "public" interface to the External login mechanism used by deployers building external logic.
The changes would only impact deployers in these cases:
Anybody copying one of the impacted login flows for private use, either directly or via adaptation into a substantially similar flow.
This is something we expect somebody might have done but is explicitly not supported because doing so would also involve references to non-API classes that are subject to change at any time so is already known to be unsafe across upgrades.
Anybody inheriting from the ExternalAuthentication class to provide an alternate concrete implementation of that class for use in a custom login flow.
This would be necessary if one were to build an alternate version of an external login flow without using non-public classes. We consider it unlikely because of the first bullet: people are taking the easy way out and copying the flows without regard for the correctness of that approach.
Anybody directly instantiating/adding an instance of the ExternalAuthenticationContext class to the profile request context tree.
This is also not something we would expect anybody to have done unless they had also duplicated other implementation classes or were, again, using implementation classes directly in an unsupported manner, so it's more likely to be a consequence of one of the first two.
Note that various third party login flow extensions are known to be impacted by this change and deployers will need to test those. Those flows generally have violated the API contract as mentioned above and will need to be modified in some cases to work with this patch release, contrary to normal assumptions about patch releases.
3.4.5 (Sep 18, 2019)
Getting issues...
This is a patch update that addresses a security advisory related to improper exposure of pairwise identifier values.
Among other fixes, it also extends support for binary LDAP attributes when using the UnboundID LDAP provider in place of JNDI. Both the older JNDI property and a new (portable) <BinaryAttributes>
element are supported. This further (we hope completely?) helps move beyond the problems noted under LDAPonJava>8 on newer Java versions.
3.4.4 (May 1, 2019)
Getting issues...
This is a patch update containing a number of bug fixes, primarily motivated by two issues in particular:
Changes to the HTTP Client code to correct an issue with client certificate authentication during TLS renegotiation.
A fix to the JPA StorageService to fail properly in the event that a case-insensitive database is used by mistake.
It also includes additional Java libraries that allow use of the UnboundID LDAP provider in place of JNDI, to work around a bug that occurs in newer Java versions. This change is not automatic, but switching providers can be accomplished with the use of a single property:
idp.ldaptive.provider = org.ldaptive.provider.unboundid.UnboundIDProvider
A more complete description of this issue can be found here. Switching the property alone will adjust the provider used, but may not work without additional modifications to LDAP settings used in relative few cases.
This setting is likely to be the default in future versions of the software.
Finally, this patch also adds deprecation warnings when features for compatibility with V2 attribute resolver scripting are used.
The following new properties have been added in this release (defaults in parentheses):
idp.ldaptive.provider (%{org.ldaptive.provider:org.ldaptive.provider.jndi.JndiProvider})
This property defaults to any pre-existing Ldaptive system property setting the provider class, or failing that, defaults to the JNDI provider for compatibility with current behavior.
3.4.3 (January 9, 2019)
Getting issues...
This is a patch update containing a fix for a regression in the TemplateAttributeDefinition caused by a late decision to deprecate the <SourceAttribute>
construct and a regression in the "renew" feature for CAS.
3.4.2 (December 19, 2018)
Getting issues...
This is a patch update containing bug fixes and addressing a security advisory.
The fix for this advisory introduced an incompatibility for those already using the impacted feature, involving CAS proxy trust configuration. If you have an existing configuration that defines a bean named shibboleth.CASProxyTrustedCertificates, usually defined in cas-protocol.xml, you will need to adjust the definition of this bean to directly expose the filenames containing the certificates as the values of the list bean instead of indirecting them through the factory bean used in older examples. The correct syntax has been updated in the example in CASProxyPKIXTrustSimple (and is shown in the file included with the distribution).
This patch includes additional deprecation warnings and an improvement to the handling of expired metadata at startup.
There is (yet another) spurious warning being produced new in this patch that can be ignored if you've removed all the legacy <SourceAttribute>
elements from your configuration:
08:38:46.114 - - WARN [DEPRECATED:118] - XML Element 'SourceAttribute', (file [/opt/shibboleth-idp/conf/attribute-resolver.xml]): This will be removed in the next major version of this software; replacement is by using <InputAttributeDefinition> and <InputDataConnector>
The warning appears incorrectly even after removal of the element(s).
There's also a regression involving this particular deprecated feature that is fixed in V3.4.3. In the meantime, upgraded systems may need to update and replace the deprecated <
Dependency>
elements in any TemplateAttributeDefinition constructs to avoid running into IDP-1386: Deprecation of SourceAttribute in Template AttrDef created a regressionClosed.
3.4.1 (November 1, 2018)
Getting issues...
This is a patch update containing bug fixes.
Several spurious or outright incorrect warnings have been suppressed, and a pair of regressions impacting upgrades have been corrected. Some warning-related issues remain and are documented under the V3.4.0 release.
3.4.0 (October 10, 2018)
Getting issues...
This is a minor upgrade containing new features and bug fixes. New material in the documentation can be identified with a 3.4 superscript.
Important Notes for Upgraders
A few issues were identified with the V3.4.0 release and are now corrected in V3.4.1 (see above); refer to the fixed issues list for details if necessary but "just use 3.4.1" and you can ignore them.
If you were improperly relying on the contents of the idp.home/webapp directory (which is built by the installer) to operate the software directly rather than using the built warfile, that was not a supported approach and it will not work with this release. As part of some related changes to the war build process, the upgrade will remove that directory (as it is considered to be "owned by the war build process") and if you have your own content in it, you should make sure it's present in the edit-webapp directory before upgrading. Do not copy any of our files or jars into that directory, it is only meant for your own additions or changed files.
A new feature supporting automatic injection of response headers such as Content-Security-Policy and Strict-Transport-Security requires the installation of a servlet filter into web.xml, installed by default for new installations and older systems that have not customized the web.xml file.
For upgrades, this could result in a change in behavior because the default property values result in denial of framing of most of the IdP's user interface, including the login form. This is consistent with the offiicial project stance not to support use of frames due to the impact on users that choose to disable third-party cookies. If you wish to, you can support frames by explicitly setting the relevant new properties (idp.frameoptions, idp.csp) to empty values.
If you have local customizations to web.xml, be sure to review the changes and if desired, add the DynamicResponseHeaderFilter declaration and mapping to your version.
A regression exists in V3.3.0 that impacts deployers who are relying on the "condition" flow error/warning feature of the Password login flow to handle an expiring password condition. To ensure correct behavior, the patch that fixes IDP-1101: SubjectC14N is not being performed for expiring-password conditionClosed should be applied. One of the corrections involves a user configuration file so will not be fully corrected during the next upgrade (and this note will be maintained for all subsequent releases).
If you use Windows and you have manually configured the idp.home property in an environment variable or Java servlet configuration system variable because of a non-standard installation location, make sure the path in the variable uses only forward-slashes and not backslashes. Use of backslashes in this path, or any path in any configuration file, is not supported and the IdP may not function properly. This is not a change, but since the IdP may have worked before despite this, and will not work now, it's being highlighted.
There's an unintentionally confusing warning in the log ("Use of secure property is strongly advised"); it's referring to the setting controlled by the idp.cookie.secure property, which defaults to false for backward compatibility but should be set to true in most cases.
In the very unlikely event that you are using an alternative JAXP XML Parser implementation, you may have relied on a technique for controlling some aspects of the parser's security settings via a property that we were forced to deprecate and turn off to prevent a future Java compatibility issue. The SystemRequirements page describes the alternative means of handling JAXP replacement for V3.4, though it remains unsupported officially.
The new support for the SAML HTTP-Artifact binding for inbound SAML 2 SSO and Logout requests requires a user-space configuration update for full functionality. A new bean has been defined to declare the default client TLS credential, shibboleth.DefaultClientTLSCredential. To enable client TLS authentication to an SP, this bean will need to be defined in conf/credentials.xml. Typically one would just declare this as an alias to the existing default signing credential (below). No configuration error will result if it is not declared. However if client TLS is indicated to be performed and the bean is not defined, a runtime error will likely result during artifact resolution with the SP. (Note that the default for artifact resolution to an SP over https on port 443 is to perform message signing rather than client TLS.)
<!-- Your IdP's default client TLS credential, by default the same as the default signing credential. -->
<alias alias="shibboleth.DefaultClientTLSCredential" name="shibboleth.DefaultSigningCredential" />
A CAS API component used for advanced proxy endpoint validation has been deprecated; this only affects deployers that wrote third-party extension components implementing that interface.
New Objects
In addition to the lists below, a variety of beans and properties have been added in support of these features:
The following new beans (or at least support/placeholders for them) have been added in this release:
shibboleth.HTTPResource
shibboleth.ResponseHeaderFilter
shibboleth.DefaultResponseHeaderMap
shibboleth.ResponseHeaderMap
shibboleth.ResponseHeaderCallbacks
shibboleth.X509TrustManager
shibboleth.DefaultParserPool
The following new properties have been added in this release (defaults in parentheses):
idp.hsts (max-age=0)
idp.frameoptions (DENY)
idp.csp (frame-ancestors 'none';)
idp.entityID.metadataFile (%{idp.home}/metadata/idp-metadata.xml)
idp.encryption.config (shibboleth.EncryptionConfiguration.CBC)
Don't change this without testing, you likely have lots of SPs that don't support AES-GCM.
idp.consent.attribute-release.userStorageKey (shibboleth.consent.PrincipalConsentStorageKey)
idp.consent.terms-of-use.userStorageKey (shibboleth.consent.PrincipalConsentStorageKey)
idp.replayCache.strict (true)
idp.xml.parserPool (shibboleth.ParserPool)
idp.audit.shortenBindings (false)
New Features
There are a large number but some of the most significant worth reviewing include:
HTTPConnector for web services integration in the attribute resolver (and all the various features that can be controlled via attributes)
Extensive customization of behavior through new metadata "tag" conventions
Non-browser Duo AuthAPI support for ECP clients
Improvements for embedding inline scriptlets in a variety of configuration scenarios, reducing the need for custom Spring beans
A new "attended startup" mode that prevents on-disk access to an unlocked or trivially encrypted private key
The ability to provision CAS services using SAML metadata for consistency and to support the new metadata-driven configuration mechanisms
Greatly enhanced context-check interceptor that can address multiple authorization scenarios at the same time
A new impersonation interceptor that supports advanced debugging or testing scenarios
Support for configurable trust for remotely accessed TLS-protected configuration resources and other HTTP client scenarios
Support for key pinning of LDAP connections (i.e., verifying only the LDAP server key, not certificate)
Support for inbound SAML 2 protocol requests for the SSO and logout profiles conveyed via the SAML 2 artifact binding.
An ldaptive system property, org.ldaptive.response.encodeCntrlChars, can be set to prevent unruly characters from appearing in the IdP's log files due to Active Directory.
Deprecation Warnings in Preparation for V4
It is expected that V3.4 will be the last minor version of V3 of the IdP. It is a goal (though not an absolute promise) for V4 of the IdP that any configuration that loads without warning on V3.4 will load in V4. To this end V3.4 has warnings against use of deprecated function. The complete list of deprecated configuration is listed here.
3.3.3.1 (June 27, 2018) (Windows Only)
This is a service release of the 3.3.3 Windows Installer that updates Jetty to 9.3.24.v20180605 to address Jetty security issues. If you did not install Jetty via the Shibboleth installer, then this update is not required (but of course you may still be affected by the security issues if you have an affected Jetty version in use).
As noted on the WindowsInstallation page, service releases (represented by the fourth version number) do not indicate an actual update to the Shibboleth software, only to third party components we support.
3.3.3 (May 16th, 2018)
This is a patch upgrade containing an update to the Spring Framework to correct a Windows-only security issue and addressing this security advisory.
3.3.2 (October 4, 2017)
This is a patch upgrade containing bug fixes and addressing this security advisory.
The Duo Java integration library in this release has also been updated to V1.3 and V2.6 of the Javascript UI.
Important Notes for Upgraders
It was brought to our attention that many may be unaware of the fact that the IdP's cookie handling defaults to cookies without the "secure" attribute. We suggest most deployers modify the idp.cookie.secure property in idp.properties to account for this.
As an exception to our normal versioning policy, this patch update includes a small feature addition, support for Base32 encoding of computed identifiers in the attribute resolver and for "persistent" NameID generation. This feature, while not the default, is strongly recommended for new deployments of these features as outlined on the relevant documentation pages. The prevalence of unsafe application handling of case-sensitive identifiers motivated the project to make this feature available ahead of V3.4.
An additional, related change is the reversal of an unofficial intention to deprecate the two data connectors related to producing pairwise identifiers in support of an expected effort on the part of at least some federations to discourage use of NameIDs in favor of SAML Attributes, necessitating continued support for these connectors within the Attribute Resolver.
3.3.1.1 (March 23, 2017) (Windows Only)
This is a service release of the 3.3.1 Windows Installer that fixes an issue with new installs.(