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

Note Generally, we recommend not using this configuration migration guide but instead deploying a clean configuration. This guide is only useful in case your Shibboleth 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 Service Provider will use an up-to-date configuration as recommended by SWITCH. Minor customizations can still be added of course.

Prerequisites

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.

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.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 SessionInitiator 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.

After Configuration Update

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:
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.

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: Lukas Hämmerle - SWITCH