SWITCH Shibboleth Service Provider (SP) Migration Guide
Table of contents
No entry yet.
This guide describes how to update the configuration of an older Shibboleth Service Provider (SP) in the SWITCHaai or AAI Test federations to the latest Service Provider configuration.
Only incremental configuration changes are covered. The changes are partly software-specific and partly federation-specific. The latter are recommendations for the SWITCHaai and AAI Test federations operated by SWITCH.
Service Provider Installed
For the following steps a Shibboleth Service Provider (SP) 2.x must be installed on your system. It is assumed that the Service Provider was configured according to a SWITCHaai or AAI Test deployment guide. If you have not yet installed the Service Provider, follow the Service Provider Installation Guide.
This section explains what configuration changes have to be performed when upgrading an older Service Provider to a newer version. The configuration changes are incremental. This means that if the Service Provider configuration currently is for version 2.2, perform the steps to get to 2.3 first and then to 2.4 and so on. Only the most essential changes are covered.
For Shibboleth Service Provider versions before 2.2 it is recommended to get clean configuration files as described above and not to upgrade the configuration.
Changes from Service Provider 2.2.x to 2.3.x
In shibboleth2.xml replace all occurrences of defaultACSIndex with acsIndex. This configuration option was renamed.
In shibboleth2.xml change to name of all Rule elements from <Rule> to <PolicyRule>. The name of this element was changed due to a naming conflict.
In shibboleth2.xml set the status handler like below in order to allow access also from the IPv6 localhost address:
In shibboleth2.xml ensure that the options signing="back" requireTransportAuth="false" are set and that encryption="false" is removed from the ApplicationDefaults element and all ApplicationOverride elements.
Changes from Service Provider 2.4.x to 2.5.x
In shibboleth2.xml remove the OutOfProcess element at the top of the file.
In shibboleth2.xml all instances of cookieProps should be set to cookieProps="https".
In shibboleth2.xml ensure that the SSO element only contains SAML2 but not SAML1 anymore
In shibboleth2.xml remove all absolute file paths. The Service Provider now automatically searches configuration files in the configuration directory and stores backup and cache files at appropriate places. In particular all instances of /etc/shibboleth/ and C:\opt\shibboleth-sp\etc\shibboleth\ can be removed
On UNIX-based systems the shibd daemon will try to start as user shibd or _shibd. Therefore, ensure that the owner of the certificate and key files is shibd or _shibd. Also, if there still are absolute paths used for metadata files, ensure that these files can be written by the shibd or _shibd users.
In shibboleth2.xml ensure that the logout handler only is local:
In shibboleth2.xml ensure that MetadataFilter element of type="Signature" is:
In the application ensure to update any direct login links that were created with the Login Link Composer as the default Session Initiator handler URL changed from /Shibboleth.sso/DS to /Shibboleth.sso/Login. Alternatively, add a SessionInitiator element with the location /DS to the file shibboleth2.xml.
If you are using the Embedded WAYF, please ensure that the setting wayf_sp_samlDSURL of the Embedded WAYF is set to var wayf_sp_samlDSURL = wayf_sp_handlerURL + "/Login";. Otherwise, the Embedded WAYF still might use the /Shibboleth.sso/DS Session Initiator that is not active anymore in the default configuration.
Alternatively to the above two methods, add in the Sessions element after the Logout element the /DS SessionInitiator again for backwards compatibility:
In the application protected by Shibboleth adapt the attribute names that the application uses to get a user's attribute from the web server environment. The reason for this change is that attribute aliases can no longer be used in future Shibboleth versions. Aliases allowed to make an attribute available in the web server environment under one or more additional names.
The attribute names used by an application should be changed like this: Shib-SwissEP-UniqueID should now be uniqueID Shib-Person-surname should now be surname Shib-InetOrgPerson-givenName should now be givenName Shib-InetOrgPerson-mail should now be mail Shib-SwissEP-HomeOrganization should now be homeOrganization Shib-SwissEP-HomeOrganizationType should now be homeOrganizationType Shib-EP-Affiliation should now be affiliation Shib-Person-uid should now be uid Shib-SwissEP-MatriculationNumber should now be matriculationNumber Shib-InetOrgPerson-employeeNumber should now be employeeNumber Shib-SwissEP-CardUID should now be cardUID Shib-SwissEP-DateOfBirth should now be dateOfBirth Shib-SwissEP-Gender should now be gender Shib-InetOrgPerson-preferredLanguage should now be preferredLanguage Shib-InetOrgPerson-homePostalAddress should now be homePostalAddress Shib-OrgPerson-postalAddress should now be postalAddress Shib-InetOrgPerson-homePhone should now be homePhone Shib-Person-telephoneNumber should now be telephoneNumber Shib-InetOrgPerson-mobile should now be mobile Shib-SwissEP-StudyBranch1 or Shib-SwissEP-swissEduPersonStudyBranch1 should now be studyBranch1 Shib-SwissEP-StudyBranch2 or Shib-SwissEP-swissEduPersonStudyBranch2 should now be studyBranch2 Shib-SwissEP-StudyBranch3 or Shib-SwissEP-swissEduPersonStudyBranch3 should now be studyBranch3 Shib-SwissEP-StudyLevel or Shib-SwissEP-swissEduPersonStudyLevel should now be studyLevel Shib-SwissEP-StaffCategory or Shib-SwissEP-swissEduPersonStaffCategory should now be staffCategory Shib-EP-OrgDN or orgDN should now be org-dn Shib-EP-OrgUnitDN or orgUnitDN should now be orgunit-dn Shib-EP-Entitlement should now be entitlement Shib-Person-ou should now be ou Shib-EP-Assurance should now be assurance Shib-primaryGroupID should now be primaryGroupID Shib-eduMember-isMemberOf should now be isMemberOf Shib-EP-DisplayName should now be displayName Shib-EP-CommonName should now be cn Shib-EP-UniqueID should now be eduPersonUniqueId Shib-SCHAC-HomeOrganization should now be schacHomeOrganization Shib-SCHAC-HomeOrganizationType should now be schacHomeOrganizationType Shib-Custom-uniBeApplAuthorisation should now be uniBEApplAuthorisation Shib-Custom-unibeUsageLimit should now be unibeUsageLimit Shib-Custom-unilMemberOf should now be unilMemberOf Shib-Custom-unigeOuCode should now be unigeOuCode Shib-Custom-uzhSAPUserId should now be uzhSAPUserId Shib-Custom-unilFacultePrincipale should now be unilFacultePrincipale Shib-Custom-fhnwIDPerson should now be fhnwIDPerson Shib-Custom-unibasChRoles should now be unibasChRoles Shib-Custom-fhnwSapUserID should now be fhnwSapUserID Shib-Custom-fhnwSapUserInfo should now be fhnwSapUserInfo Shib-Custom-fhnwUPN should now be fhnwUPN Shib-Custom-UserType should now be UserType Shib-Custom-fhnwOeID should now be fhnwOeID Shib-Custom-UzhSAPUserIdStaff should now be uzhSAPUserIdStaff Shib-Custom-swissLibraryPersonAffiliation should now be swissLibraryPersonAffiliation Shib-Custom-swissLibraryPersonResidence should now be swissLibraryPersonResidence Shib-Custom-fschImapPW should now be fschImapPW
Changes from Service Provider 2.5.x to 2.6.x
The optional configuration setting ignoreCase was renamed to caseSensitive in order to permanently fix a security bug. Therefore, the existing configuration may need update. Search for all occurrences of ignoreCase in the Shibboleth configuration directory (if your SP was configured using the SWITCH Service Provider configuration guide, there are no occurrences). Then rename ignoreCase with to caseSensitive and toggle its value (true should become false and vice versa) to reflect the meaning of the new wording.
It is recommended to add the option verifyBackup="false" to the element MetadataFilter of type type="Signature". This configuration will instruct the Service Provider to not verify the backing file at startup of the SP, which will speed up system startup. As long as the backing file is not manually edited or overwritten by any other process than shibd, verification of metadata should not be needed at each start of shibd.
Additionally we strongly recommend to add to all Sessions elements in your shibobleth2.xml configuration the following setting: redirectLimit="host".
This setting prevents an open redirect security issue. More information on the options of this setting are documented in the Shibboleth wiki on the Sessions element.
After the configuration update, the configuration should be checked.
On Unix-based operating systems (including Mac OS X) run in a terminal the command:
sudo shibd -t
On Windows run the command:
If the last line of the output is the following message, everything is as expected:
overall configuration is loadable, check console for non-fatal problems
If there are any ERROR messages, it is strongly recommended to have a look at the problem.
Messages with log level WARN are generally not problematic but it is still recommended to examine the cause of the messages as they could pinpoint to deprecated features or minor configuration problems.