Switch Shibboleth Service Provider (SP) Migration Guide

Table of contents

  1. No entry yet.

Introduction

This guide describes how to update the configuration of an older Shibboleth Service Provider (SP) in the Switch edu-ID Federation (in naming transition from SWITCHaai Federation) or the AAI Test Federation 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 Switch edu-ID Federation and the AAI Test Federation operated by Switch.

Note: All Shibboleth SP 2.x versions are end of life and are vulnerable. SP 2.6.1, has been released in November 2017.

Note on migration or clean installation
Generally, we recommend to deploy a clean configuration instead of using this configuration migration guide.
This guide is only useful in case your Shibboleth SP configuration deviates heavily from the standard deployment as recommended by Switch.
If the old configuration was not customized much, it is better to use the standard configuration guide by completing the setup profile and then deploying the custom-tailored configuration files from the Quick Configuration Download section. That way, the Shibboleth Service Provider will use an up-to-date configuration as recommended by Switch. Minor customizations can still be added of course.

Prerequisites

On Debian/Ubuntu: Drop the obsoleted SWITCHaai Package Repository
Since 30. November 2021, Switch no longer provide updates for its own Debian and Ubuntu packages. Therefore, remove the SWITCHaai package repository from your system, uninstall packages shibboleth and switchaai-apt-source, then remove any remaining APT configuration for the repository (if any).
This won't uninstall the Shibboleth SP and the currently-installed SWITCHaai SP packages will remain until a newer version is available from the distribution's official repository. 
apt remove shibboleth
apt-mark manual libapache2-mod-shib
apt purge switchaai-apt-source
rm /etc/apt/trusted.gpg.d/SWITCHaai-swdistrib.gpg /etc/apt/sources.list.d/SWITCHaai-swdistrib.list
apt update
On Linux with RPM: Is the Shibboleth RPM repo configuration up-to-date?
Since Shibboleth SP v3.3, a new RPM repository needs to be configured. It is now named shibboleth, no longer security:shibboleth.
Checkout the RPM Install page in the Shibboleth Wiki to fetch the new repo file.
Service Provider Installed
For the following steps a Shibboleth Service Provider (SP) 2.x or 3.x must be installed on your system. It is assumed that the Service Provider was configured according to a Switch edu-ID Federation or AAI Test Federation Configuration Guide. If you have not yet installed the Shibboleth Service Provider, follow the Shibboleth Service Provider Installation Guide for a clean installation.

Configuration Changes

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.x to 3.0.x

Changes from Service Provider 2.2.x to 2.3.x

  1. In shibboleth2.xml replace all occurrences of defaultACSIndex with acsIndex. This configuration option was renamed.
  2. 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.
  3. In shibboleth2.xml set the status handler like below in order to allow access also from the IPv6 localhost address:
    <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1 130.59.138.32"/>
  4. In shibboleth2.xml ensure that the options signing="back" requireTransportAuth="false" are in the ApplicationDefaults element and all ApplicationOverride elements.

Changes from Service Provider 2.3.x to 2.4.x

  1. In shibboleth2.xml ensure that the option safeHeaderNames="true" to the ISAPI element if the web server is Microsoft IIS.
  2. In shibboleth2.xml ensure that in all Sessions elements (there might be more than one), the option relayState="ss:mem" is set.
  3. In shibboleth2.xml add a Discovery Feed handler after the Handler element of type="Session":
    <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
  4. In shibboleth2.xml ensure that in all Sessions elements (there might be more than one), the option cookieProps="; path=/; secure; HttpOnly" is set.
  5. In shibboleth2.xml set the status handler like below in order to allow access from a Resource Registry backup IP:
    <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1 130.59.138.32 130.59.10.146"/>
  6. 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

  1. In shibboleth2.xml remove the OutOfProcess element at the top of the file.
  2. In shibboleth2.xml all instances of cookieProps should be set to cookieProps="https".
  3. In shibboleth2.xml ensure that the SSO element only contains SAML2 but not SAML1 anymore
  4. 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
  5. 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.
  6. In shibboleth2.xml ensure that the logout handler only is local:
    <Logout>Local</Logout>
  7. In shibboleth2.xml ensure that MetadataFilter element of type="Signature" is:
    <MetadataFilter type="Signature">
	<TrustEngine type="StaticPKIX"
				 certificate="SWITCHaaiRootCA.crt.pem"
				 verifyDepth="2"
				 checkRevocation="fullChain"
				 policyMappingInhibit="true"
				 anyPolicyInhibit="true">
		  <TrustedName>SWITCHaai Metadata Signer</TrustedName>
		  <PolicyOID>2.16.756.1.2.6.7</PolicyOID>
   </TrustEngine>
</MetadataFilter>
  8. 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 Session Initiator again for backwards compatibility: 
    <SessionInitiator type="Chaining" Location="/DS">
  <SessionInitiator type="SAML2"/>
  <SessionInitiator type="SAMLDS" URL="https://wayf.switch.ch/SWITCHaai/WAYF"/>
</SessionInitiator>
  9. 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

  1. 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.
  2. 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.

Changes from Service Provider 2.6.x to 3.0.x

  1. Please follow the official Shibboleth SP 2.x to SP 3.x Upgrade instructions.
  2. 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 is documented in the Shibboleth wiki on the Sessions element.
  3. When running the Shibboleth SP on Windows with IIS, please also follow the specific instructions on upgrading older ISAPI configurations.

Changes from Service Provider 3.0.x to 3.2.x

  1. Read the official Shibboleth SP 3.x Release Notes.
  2. Namely the SameSite topic should be studied. Consider temporarily activating sameSiteFallback if the service's user base is likely to connect with Safari and embedded browsers on macOS 10.14 and all browsers on iOS 12.
  3. In shibboleth2.xml replace in MetadataFilter the type name EntityRoleWhiteList (deprecated since v3.2) with the new EntityRole type name.
  4. Compare the existing attribute-map.xml and attribute-policy.xml files with the new versions referenced in the Shibboleth SP 3.2 Configuration Guide.
    Namely the XML schema for attribute-policy.xml changed. Without adopting the new syntax, the shibd process will report many WARN messages on every restart. Only by eliminating them all, the SP configuration is well prepared also for the next SP version to come.
    Note: You need to update both files together, since some configurations in attribute-map.xml rely on configurations in attribute-policy.xml.

Changes from Service Provider 3.2.x to 3.4.x

  1. Read the official Shibboleth SP 3.x Release Notes.

Configuration Update Postprocessing

After the configuration update, the configuration should be checked.
On Unix-based operating systems run in a terminal the command: 

sudo shibd -t

On Windows run the command: 

C:\opt\shibboleth-sp\sbin\shibd.exe -check

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.
Since SP v3.3, Shibboleth.DEPRECATION is used to hint to configuration elements in your configuration that might disappear in future versions. If possible, eliminate them now and do not wait until the configuration breaks with possibly the next version

Mistakes and Improvements? If you found an error or a typo or if you have suggestions for improvements, please . Your contributions are appreciated very much and they will help your colleagues.

Additional Information

References

Version Information

URL: index.html
Author: eduid-support@switch.ch