Page Comparison

...

The Old System

There are some steps to take to "clean up" your V2 configuration to prevent inadvertent changes in behavior after you upgrade, principally related to Name Identifier handling. You need to ensure that any integrations your old system is supporting through the use of Name Identifiers are configured correctly or you will be likely to observe changes in this area. Specifically, you need to ensure that the selection of the appropriate Name Identifier format is being done appropriately. There are only three appropriate ways to do this with V2, as documented:

• the SP selects the format itself at runtime (quite rare)
• the SP's metadata contains one or more <NameIDFormat> elements indicating what it needs
• the IdP configures a precedence of formats to use with an SP based on a relying party override using the nameIDFormatPrecedence attribute

Those are the only three mechanisms that are supported, and they are supported in identical fashion in V3, ensuring compatibility in format selection.

The problem is that many deployers did not understand how to do this correctly, and there are a lot of legacy systems around that are selecting formats in an inappropriate "ad hoc" fashion, usually by suppressing the release of IdP attributes associated with non-desired formats using an attribute filter policy (i.e., in layman's terms, a policy saying to deny the release of one or more attributes for a particular SP). It is very rare for a deny rule to be needed in either V2 or V3, so such a filter rule tends to be a red flag that the system may have been setup incorrectly with respect to Name Identifier format selection.

After upgrading such a system, SPs that were receiving a Name Identifier in particular formats may end up receiving a transient format. This is a clear sign that the original V2 configuration was not correct. Cleaning this up ahead of time will prevent this problem from occurring.

The New Environment

Refer to the SystemRequirements page for details on supported software platforms. There are differences, so your existing system may well not support the new version.

...

• The vt-ldap JAAS module provided with V2 has been replaced with a newer implementation based on the successor project called ldaptive. While the newer module is generally more capable (and has the advantage that it's fully supported), there can be differences in configuration.
• The login form customization features in V2 were based on JSP, while Velocity templates are the strongly recommended approach in V3. Even if JSP is used, there will be inevitable changes required. In most cases, it's best to leave the default form in place during initial testing and save the UI migration for a later step.

Name Identifier Handling

If you're experiencing changes to the Name Identifier format particular services are receiving, refer to the warning in the first section above, under "The Old System". The change is caused by a mistake in your older configuration that has been carried forward and is now being exposed. You may want to go back and make corrections to the original system and then redo the upgrade (or at least manually apply the same corrections to the new system).

Initial Testing

After starting the new version for the first time, watch for any errors in the log, and make a note of any warnings; most of those will be due to the use of a legacy relying-party configuration, but some will also note use of deprecated features or syntax. You can ignore deprecation issues until after you have a stable system.

...