OIDC OP Upgrading

Owned by Scott Cantor
Last updated: Nov 30, 2022 by Tom Zeller

Upgrading from Official Releases

Starting with V3.0 of this plugin/extension, upgrades will be managed via the PluginInstallation process and every attempt willl be made to maintain compatibility to the greatest extent possible.

Upgrading from Pre-Official Versions

There are unfortunately many necessary differences between the pre-V3.0 extension and this "official" version. We have tried to minimize this, but also have taken advantage of these changes to automate and simplify as much as possible for future deployers. Obviously this process should always be performed on a non-production system, and never directly in production first.

While inconvenient, the suggested approach to move from the older versions to this (and later) versions is to "remove" the original version first. There is no automatic upgrade path and trying to install the new version "on top" will leave a mixture of old and new libraries and files and will not function.

Removal, in this context, means commenting out additions made to existing IdP configuration file (including any Spring <import> statements added), temporarily moving OIDC-specific configuration files to a backup location (if needed), and removing JAR files added to the IdP and rebuilding the warfile to exclude them. This is not necessarily intended to result in a 100% working system but should avoid as much contamination as possible during the installation of the new version and should in most cases at least function for non-OIDC purposes.

After the removal and rebuild, follow the documentation to install the plugin(s) required (which will automatically enable the OP "module"). Once this is complete, there are a small number of manual steps still required to complete installation. Some of the manual changes and imports required in the previous versions are no longer needed.

Finally, you should review the new documentation in the areas that address the settings you previously added and compare those sections to the original documentation to understand the differences. This consists in most cases of class name or bean name differences, or in the case of custom XML within the Attribute Resolver and Attribute Filter configurations, changes to the xsi:type values used for various features and to the XML namespace boilerplate at the top of those files.

When complete, you will have copied back changed versions of some files used before, adjusted settings in other files, and should be close to a system working hopefully close to identically as before. You should have no references to "geant" or "csc.fi" XML namespaces, classes, or types in your configuration at that stage, and should remove any that remain.

As we identify specific "gotcha" issues or subtle differences, we will address them here.

No Longer Needed

These files are no longer supplied or assumed, and if you have unrelated definitions or settings in them, you will probably need to move them:

  • conf/global-oidc.xml

  • conf/oidc-relying-party.xml

  • conf/services-oidc.xml

  • conf/authn/authn-comparison-oidc.xml

If you previously were instructed to, and did, set the idp.service.attribute.registry.namingRegistry property in services.properties, you should remove it entirely.

The oidc-subject.properties and idp-oidc.properties files were merged into a single, new oidc.properties file. This change will typically require altering the idp.additionalProperties property that may reference the old files. (Furthermore, IdP V4.1+ supports auto-locating and loading additional properties, provided the new idp.searchForProperties setting is set to true, so this is usually the simplest way to proceed now.)

Other Changes

The default template/example that was created in static/.well-known/openid-configuration file was moved to static/openid-configuration (eliminating the extra hidden directory since this isn't automatically exposed to web clients without specific/local steps anyway).

The directive to adjust conf/relying-party.xml to include p:responderIdLookupStrategy-ref="profileResponderIdLookupFunction" in various places is obsolete and must be removed.