The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

SPUpgrades

Owned by Scott Cantor
Last updated: May 03, 2010Version comment
4 min read

The upgrade process from 1.3 to 2.x is NOT automated or seamless, but new releases are completely compatible with the older releases functionally. In other words, while the configuration is somewhat different (very different in some spots), much of it is similar, and it is always possible to configure the new software to behave functionally the same as the old software, so you do not have to change applications unless you want to take advantage of new features or improvements.

Mechanics of Upgrading

The actual update process is platform-specific, but at this point, all of the supported packaging techniques include protection of configuration files across uninstalls or updates. Most platforms (e.g. Windows) require a full uninstall/removal followed by a reinstallation of the new software. Others (e.g. RPMs) can be upgraded in place followed by a manual conversion of configuration details.

Note that on Windows, uninstalling tends to hang the Windows installer unless you go through the Add/Remove dialog box and select "Change" followed by "Remove", instead of a direct removal. If you have specific questions, you can ask on the mailing list.

Configuration Equivalencies

Most of the content of shibboleth.xml can be mapped to settings in shibboleth2.xml The correspondence is strong enough that a style sheet is actually included to perform a simplistic conversion (see below).

The content of the old AAP.xml file is expressed (in very different syntax) in the attribute-map.xml and attribute-policy.xml files.

Keys and Certificates

Most Shibboleth deployments are moving toward a model of exchanging self-signed certificates rather than relying on CA hierarchies. This does not mean you need to change your key or certificate when upgrading. However, since the example configuration and various scripts check for the files sp-key.pem and sp-cert.pem, you should probably rename your existing key and certificate files to match this convention. If you do an installation first, you may find that it has generated those files already, but you can safely delete them and rename your old key and certificate afterward. Just be sure you know which files are which so that you don't accidentally delete your real key.

Headers and Environment Variables

On IIS and Sun web servers, attribute information is supplied only using HTTP request headers. If you're missing information after the upgrade process (and the logs indicate you're still receiving it), the answer is most likely found in a difference in header names in the new configuration. This can be adjusted by altering the configuration or altering the application, but you should take special care to review the material at secadv_20090615 to ensure a safe configuration.

In the case of Apache, either request headers or the safer option of environment variables can be used. As of 2.x, the default has changed from headers to environment variables. This is an incompatible change because headers end up prefixed by "HTTP_" while environment variables do not. As a result, you can choose to alter your application to account for the change, or consciously choose to re-enable header support with the Apache command ShibUseHeaders On. (You can also disable the use of the environment with ShibUseEnvironment Off.) It's a good idea to use environment variables if at all possible.

For complete information, see NativeSPAttributeAccess.

REMOTE_USER

With the new software, you can make a systematic choice as to which attribute(s) to use as REMOTE_USER for your application by setting the REMOTE_USER property in the <ApplicationDefaults> element in shibboleth2.xml. You can provide a list of attribute names to use, and the first one found will be used. The "names" used correspond to the shorthand names configured in the attribute-map.xml file you use, and in turn become header or variable names.

If you find that the value in REMOTE_USER changes to a different attribute after upgrading, simply adjust the property as needed.

Note that the use of the "remote-user" or "HTTP_REMOTE_USER" header on IIS is NOT recommended, because it is not really compatible with REMOTE_USER-based applications anyway. It's better to rely on an explicit header in such cases.

For complete information, see NativeSPAttributeAccess.

Upgrading your Configuration

While it is possible to "automatically" convert shibboleth.xml into shibboleth2.xml using an included script, it is suggested that you use this at most for guidance in applying the necessary changes manually rather than attempt to use the converted file directly. Instead, please follow the usual installation and configuration instructions, adjusting for the fact that you're using an existing key and certificate. Your original providerId setting is the same as the entityID required by the upgraded software and the other changes should be similar, often identical.

In most cases, you can literally copy the contents of your original <RequestMap> element directly into the new file as is. IIS installations can also generally copy the contents of the <ISAPI> element over as well. This generally constitutes the bulk of the changes required.

For sites that have utilized the <Application> element to override settings for virtual hosts or to deploy additional logical SPs on a single server, you can generally convert such elements into <ApplicationOverride> elements, also converting any providerId attributes into entityID attributes.