URL: 
http://www.switch.ch/aai/docs/shibboleth/SWITCH/2.0/sp/migration-sp-2.0.html
Author: Lukas Haemmerle, Halm Reusser - SWITCH
$Date: 2008/12/22 12:57:32 $
$Revision: 1.6 $ 

Migrate a Shibboleth Service Provider 1.3.x to 2.x

Table of contents

  1. Introduction
  2. Prerequisites
  3. Upgrade procedure
  4. Adapting applications running on Apache
  5. Clean-up old version
  6. References

1. Introduction

Note For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the deployment section of the SWITCHaai website.

This guide describes the migration process that is needed when upgrading a Service Provider 1.3.x to version 2.x

The migration process is composed of the following tasks:

  1. Backup old configuration files and certificates
  2. Install Service Provider 2.x
  3. Upgrade Resource Description in Resource Registry
  4. Download and install new custom configuration from Resource Registry
  5. Test Service Provider
  6. Adapt application or web server configuration if necessary
  7. Test application
  8. Remove old Service Provider 1.3.x

2. Prerequisites

It is assumed that a working Service Provider 1.3.x with working certificates has been installed and registered already with the Resource Registry.

3. Upgrade procedure

3.1 Backup

Before upgrading a Service Provider, it is recommended to create a backup of all necessary configuration files and certificates that were used by version 1.3.
In particular one may create a backup of /etc/shibboleth, although the SWITCH installation guides were created in a way that the new Shibboleth 2 installation won't interfere with the old 1.3 one. However,1.3 and 2.x cannot be run at the same time.

3.3 Install Service Provider 2

Use the SWITCH Service Provider deployment guides to install a Shibboleth Service Provider 2.x. The configuration sections as well as the Resource Registry section can be skipped however.
In order to make sure that everything went fine, it is recommended to have a look at the shibd.log file in /var/log/shibboleth2/. Make sure that there are no ERROR or CRIT messages in the log since restart.

3.4 Adapt Resource Description to support SAML 2

Once the Service Provider is installed, one should go to the Resource Registry and edit the Resource Description that corresponds to the upgraded Service Provider.
In particular the following sections of the Resource Description should be edited:
Service Locations:
Shibboleth 1.3 supported at only two service locations (Assertion Consumer and Artifact service locations). Shibboleth 2.x however supports many mores because more protocols and more bindings are supported.
Service Locations
The easiest way to add these service locations is to use the "Shibboleth 2.x assistant". It will ask for the Shibboleth handler URL, which usually is of the form https:// + #HOSTNAME# + /Shibboleth.sso. If the URL is provided, the assistant will complete all the service location fields.
Used Certificates:
In order to benefit from some of the new (security) features of SAML 2, it is essential to include the certificate used by the Service Provider in the metadata. Therefore, one should add the certificate used by the Service Provider in this section.
Used Certificates
Again, the easiest way to do that is to run the assistant. Unless the Service Provider 2.x has already been configured, one should click on "Cancel" for the first question. This way the certificate used by the web server is downloaded to complete the form, assuming that Shibboleth uses the same certificate as the web server.
All the other properties and settings of the Resource Description don't have to be adapted for Shibboleth 2.x. However, it may be a good idea to have a look at them anyway.
Resource Menu

4. Adapting applications running on Apache

Note This chapter is only relevant if a PHP/PERL/other web application needs to access any Shibboleth attributes. If Shibboleth is only used to authorize users via .htaccess files or the httpd.conf, this section can be skipped.

4.1 Make attribute names accessible to application again

On the side of the Service Provider the step from 1.x to 2.x was mostly an extension and not a complete rewrite as for the Identity Provider. Nevertheless, some changes were introduced regarding attributes that one should be aware of when using Apache as web server.
Shibboleth 1.x made attributes available to the environment using header variables. For this to work Apache transformed the attribute names from Shib-EP-Affiliation as it was specified in the attribute acceptance file (AAP.xml) to HTTP_SHIB_EP_AFFILIATION, which was the name an application had to access the attribute.
Shibboleth 2.x however by default doesn't provide attributes as request headers anymore but as environment variables. There are security reasons that made the developers change the default behavior. Under some circumstances with some web servers from a very well known vendor, request headers can be more easily spoofed than environment variables. Another advantage of environment variables is that the attribute names now look as specified in the attribute-map.xml file. Therefore, the above attribute also will have the name Shib-EP-Affiliation when accessed by PHP/Perl/ application.
The problem arising from this however is that these applications have to be told to use this new attribute name instead of the old one. Otherwise, the application may stop to work properly. To get around this issue one can choose one of the following solutions:

Make Shibboleth use old-style request headers
The Service Provider 2.x still has an option to use the old behavior where not only the new environment variables are used to populate the attributes, but also the old-style request headers.
This behavior can be activated by using the ShibUseHeaders On directive like in the following example:
 <Location /my-application>
  AuthType shibboleth
  ShibRequireSession On
  ShibUseHeaders On
  require valid-user
 </Location>
		
Using this option allows an easy migration because nothing else has to be changed for it to work. However, in the long run, it is strongly recommended to adapt the applications like described below and then remove the ShibUseHeaders On directive in order to increase security.
Note If Tomcat is used behind an Apache web server, it most likely is required to have ShibUseHeaders On directive because Apache only forwards request headers but not environment variables to Tomcat. Alternatively, Apache directives like JkEnvVar Shib-Identity-Provider could be used to explicitly tell Apache also to forward environment variables.
In Tomcat, Shibboleth attributes can be accessed by using their unmangled name, e.g. with request.getHeader("Shib-EP-Affiliation")
Adapting applications to use new attribute names
Applications like certain e-learning platforms like Moodle or Ilias often need access to the Shibboleth attributes for authentication. Therefore, they often have configured a mapping that tells the application to access an attribute. For a Shibboleth 2.x upgrade this mapping needs to be updated in order to reflect the new attribute names. This means that it should be made sure that the application accesses attributes using the names specified in the attribute-map.xml file. E.g. if there is a line in a PHP script like:

			$userAffiliation = $_SERVER['HTTP_SHIB_EP_AFFILIATION'];
		
This should be replaced by:

			$userAffiliation = $_SERVER['Shib-EP-Affiliation'];
		

4.2 Common problems

The following list gives an overview about common problems.
Application doesn't work anymore or says user is not authenticated
Most probably the application cannot find any attributes when you are authenticated. This means that one of the following conditions applies:
User is not authenticated
Make sure that Shibboleth requires an authentication when accessing protected areas of a web application. If there is no redirect to the WAYF or and Identity Provider upon accessing protected content, then most probably the web server configuration should be looked at and it should be made sure that Shibboleth enforces authentication and does access control.
Attributes are not available
Even if a user was successfully authenticated at the Identity Provider, it could be that her attributes are not available due to a configuration error. Please have a look at the shibd.log file when accessing a protected web page and check whether there were any error messages logged.
User is authenticated but application cannot access attributes
If there are attributes available but the application that is protected with Shibboleth cannot see them, it is most likely the case that the application doesn't see the attributes because it assumes them to be named differently. Try to use the above-mentioned ShibUseHeaders On directive in order to get the old Service Provider behavior back, then try again. If it works now, it should be considered adapting the mapping that the application uses to use the Shibboleth attributes.
No log files are written
Check the permissions of the log files or the path for the log files set in /etc/shibboleth2/native.logger or /etc/shibboleth2/shibd.logger .

In case the error cannot be found or the error message looks confusing, the Shibboleth SP 2 - Common Errors web page may help further.

5. Clean-up old version

After the application has been adapted, tested and found to be working, any files form the old Shibboleth Service Provider 1.3.x version should be removed.
In particular the following things should be removed

6. References

--
$Id: migration-sp-2.0.html,v 1.6 2008/12/22 12:57:32 haemmer Exp $