Service Provider V3.0 Upgrade
Announcement
July 17, 2018 - From: Scott Cantor - To: Shibboleth Announcements List
The Shibboleth Project is pleased to announce that V3.0.0 of the Service Provider software is now available. This release is a largely compatible upgrade for the previous versions and supersedes those releases. There are no current plans to maintain the older SP and library branches based on experiences with the upgrade process so far but this is subject to change if unexpected problems arise.
The documentation for this release has been migrated from the old wiki space to a new dedicated space, which we hope is better organized and will be less cluttered by IdP material.
Upgraders should carefully review the Release Notes and Upgrade material beforehand.
Notable Changes from SP V2.6
"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."
- At NCSU, we recommend SPs sign SAML login messages so they may refer to custom endpoint URLs without having to register every possible endpoint in the SP metadata. This change will affect those signed messages, making them more trustworthy.
Web servers using MacOS and running the shibboleth SP should note: "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."
"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."
- We will continue to build copies of the SP RPM packages for 64-bit versions of RHEL/Centos 6 and 7. They will be available in the vision4 repository. You are also welcome to pull directly from the source repos if you prefer.
There is significant new functionality in the IIS module for Windows. See the Release Notes section "IIS7" for details.
Sites using Shibboleth on multiple identical backend servers may want to look into the "Stateless Clustering" section for a new method of sharing SP sessions between servers.
- We have historically solved this problem by using a persistent load balancer to ensure a given client is always returned to the same backend web server for the duration of a Shibboleth session.
New Configuration Changes
These are changes that will be applied by default when an new SP is setup. Existing SPs should continue to behave normally when an old (V2.6) configuration is used.
New configurations will generate two SP key pairs, assigning one to encryption and one to signing. Existing SPs may continue to use a single SP key for both functions.
"The default configuration specifies a more restrictive and secure set of TLS ciphers to support when contacting other systems."
"SAML 1.1 support is not enabled by default."
- At NCSU we rarely use SAML1.
"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."
- If you are parsing or storing shibboleth logs, you may notice this change and a change in the transaction log format.
"The attribute mapping rules and priority for populating REMOTE_USER have been refreshed to reflect modern (and post-modern utopian) practices."
Upgrading from V2.6 on RHEL/Centos 6 or 7
In place upgrade without changing config files
If you have a Yum repository already setup to provide the Shibboleth packages for your server, you can simply "yum update" to load the new software in place. It is supposed to continue to work normally using existing v2.6 configuration files. In our tests they worked fine.
yum update curl-openssl shibboleth
# should update around 9 to 11 packages
systemctl restart shibd
systemctl stop httpd
systemctl start httpd
# hard stop so the new mod_shib will load correctly
# restart will continue to run mod_shib 2.6.x from memory
# now test to confirm you can still login to an SP-protected site
Upgrading configuration files
The format of the shibboleth2.xml file has not changed very much with version 3. There are a few subtle differences. We have provided new template files that you can download:
- Sample 3.0.x shibboleth2.xml
- IIS Installs should use Sample 3.0.x IIS shibboleth2.xml
- Sample 3.0.x attribute-map.xml
You should be able to copy your entityID and any other customizations that you've made from your 2.6.x copy of shibboleth.xml into the new template file. Once done, make a backup of the working v2.6 file and replace it with the new v3 file. Now restart shibd and httpd, and verify that the service is still running correctly.
The attribute-map.xml has not changed from version 2.6. However, we have added a few new attributes to our service. If you need to use those attributes, now is a good time to update the map file.