The Shibboleth V1 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.

UpgradeIdP

Owned by Scott Cantor
Last updated: May 09, 2012 by ChadCVersion comment

Upgrading an existing !IdP

Upgrading an !IdP from 1.2 to 1.3

!IdP Configuration Files

In Shib1.2, all !IdP configuration files were stored with the .war in WEB_INF/classes/conf . Beginning in Shib1.3, all configuration and logging is stored outside the .war in a location specified during installation (hereafter referred to as IDP_HOME). origin.xml has been renamed to idp.xml and has seen several changes its schema -- see the IdP Configuration Guide for more information. Any resolver and ARP configurations that worked in Shib1.2 should also work in 1.3.

Protocol Handlers

Shibboleth 1.3 includes a significant change in how the !IdP responds to requests. Protocol Handlers are now defined and mapped to URLs in idp.xml, and must be tweaked a little to provide a seamless upgrade to 1.3. There are two basic ways to go about this -- change your configuration to match your old metadata, or update your metadata to match the new defaults.

Change configuration

  • Locate the ProtocolHandler statements at the bottom of IDP_HOME/etc/idp.xml and edit the locations to match your metadata. For example, you'll likely need to change the webapp name to something other than 'shibboleth-idp' (probably just 'shibboleth').
  • The Handle Service is now the SSO Protocol Handler, so you will need to change the location from [...]/shibboleth-idp/SSO to your Handle Service URL (probably =[...]/shibboleth/HS=)
  • Finally, you must also edit the servlet mappings. Open WEB-INF/web.xml and change the url-pattern for SSO to /HS . Whenever you upgrade Shibboleth in the future, this file will be overwritten and you will need to make this change again.

Update metadata

Methods for updating metadata will differ between federations.

Gotchas

If in addition you have upgraded tomcat to tomcat 5.5 you will also have to add request.tomcatAuthentication="false" in the AJP connector segment of the server.xml, this is new in tomcat 5.5, in 5.0 tomcat was told not to take external authentication by configuration in the workers.properties file.

Also when dealing with service providers who are not upgraded to 1.3 you will have to add a
schemaHack="true" attribute to the appropriate RelyingParty elements in your idp.xml file or you send out attributes in a format the old service providers don't understand
e.g. my relying pary element for the sdss fed now looks like

<RelyingParty name="urn:mace:ac.uk:sdss.ac.uk:federation:sdss" schemaHack="true"
				  providerId="urn:mace:ac.uk:sdss.ac.uk:provider:identity:lock.ncl.ac.uk"
				  signingCredential="sdss_cred">...
</RelyingParty>

Upgrading a 1.3 !IdP

As of Shibboleth 1.3, the !IdP by default has been installed with the configuration files stored outside the web application itself. This structure makes upgrades of Shibboleth extremely straightforward; however, future versions of Shibboleth may have modified prerequisites which should always be considered when updating(e.g. Java 1.3 will likely be unsupported by Shibboleth 2.0). To update an !IdP:

  • Download and unpack the .tar file
  • Run ./ant install in the root of the unpacked tarball and answer the simple questions.
  • The ant installation script will detect the old configuration files and will not overwrite them.
  • It might be necessary to delete the Tomcat webapp IdP directory (not the war file) so that it can be rebuilt correctly from the new war file. Be aware of your site customizations if applicable. 
  • Reboot Tomcat.

%COMMENT%