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.

NativeSPUpgradeOlder

Owned by Scott Cantor
Last updated: Jun 30, 2010Version comment

Upgrading a version 1.3 SP to the newer release is not automated or seamless, but the new release is 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 your 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.

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 an example conversion (see below).

The content of the AAP.xml file is expressed (in very different syntax) in the attribute-map.xml and attribute-policy.xml files. In most cases, the configuration supplied should provide a compatible configuration for attribute usage, aside from a few additional settings that may need to be adjusted.

Keys and Certificates

You do not need to, and generally shouldn't, 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 a fresh installation, 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

See also the NativeSPAttributeAccess topic.

For non-Apache web servers, attribute information is supplied only using HTTP request headers in both old and new versions. 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 https://spaces.internet2.edu/display/SHIB2/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 (at least in most programming scenarios). 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.

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 attribute in the <ApplicationDefaults> element in shibboleth2.xml. You can provide a list of attribute names to use, and the first one with a value set will be used. The "names" used correspond to the shorthand names configured in the attribute-map.xml file, and in turn become header or variable names. As a result, anything you choose as REMOTE_USER appears twice, once by its original name.

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.

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 primarily for guidance in applying the necessary changes manually rather than attempt to use the converted file directly.

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, once you copy over the old providerId setting into the new entityID setting.

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