{color:red}{*}This page is under construction{*}{color}

h4. Summary

The following steps should be followed to migrate a Shibboleth service provider (web server application) from Shibboleth 1.3 to 2.x:

* [Back up old configuration files|#backup]
* [Install Shibboleth SP 2.x|#install]
* [Configure the SP software|#configure]
* [Test the SP software|#testshib]
* [Adapt the web application and server configurations as necessary|#adapt]
* [Test the web application|#testapp]

{anchor:backup}

h4. Back up old configuration files

If you install from RPM (strongly recommended), the configuration files, error pages, certificates, etc., in the {{$PREFIX/etc/shibboleth}} directory should be saved when you install the Shibboleth 2 SP RPMs.  But we still recommend making a copy of the /etc/shibboleth directory for safety.  You should also save a copy of the shibd init script ({{/etc/rc.d/init.d/shibd}}).

{anchor:install}

h4. Install Shibboleth SP 2.x

We strongly recommend that you download and install the 2.x SP RPMs from the [Internet2 downloads site|http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/latest/RPMS/].  It is not necessary to download the {{\-debuginfo}}, {{\-devel}}, or {{\-docs}} RPMs.

{anchor:configure}

h4. Configure the SP software

The quickest way to get started is to copy the following files from the Touchstone locker ({{/mit/touchstone/config/shibboleth2-sp}}) into /etc/shibboleth:

* {{attribute-map.xml}}
* {{gen-shib2.sh}}
* {{shibboleth2.xml.in}}

Then run the gen-shib2.sh script, and answer the prompts, to generate shibboleth2.xml.  For example:
{noformat}# cd /etc/shibboleth
# cp /mit/touchstone/config/shibboleth2-sp/* .
# sh gen-shib2.sh
{noformat}

Note that any changes to the shibboleth2.xml, attribute-map.xml, and attribute-policy.xml files will be detected automatically, i.e. without requiring a restart of shibd.

Also, note that Shibboleth 2.x can check for and reload metadata automatically, obviating the need for a separate cron job to do so.  The Touchstone-supplied shibboleth2.xml template is configured to do so for the MIT metadata, so, once 2.x is deployed, the cron job required in 1.3 can be removed.

{anchor:testshib}

h4. Test the SP software

{anchor:adapt}

h4. Adapt the web application and server configurations as necessary

The names of the environment variables mapped to Shibboleth attributes have changed in 2.x, to non-Shibboleth-specific names.  For example the user's display (i.e. full) name is now passed via the {{displayName}} variable, whereas in 1.3 it was passed via {{HTTP_SHIB_INETORGPERSON_DISPLAYNAME}}.

Note that, by default, the Shibboleth-related headers are *not* passed to the application in 2.x; this is to avoid any problems with header spoofing.  If you do need to use these headers in your application, add the following directive to your Apache configuration:
{code}ShibUseHeaders On
{code}
{anchor:testapp}

h4. Test the web application