Guidelines for upgrading IAM to 8.0

This article provides high-level guidelines for updating IAM 7.x to 8.0. It is not a detailed update instruction but it helps plan the upgrade and better understand the update process.

What is special about IAM 8.0?

IAM 8.0 is a major release containing breaking changes. This means that manual changes are required to upgrade even if no new features are used. It is thus not possible to just upgrade the configuration.

  • Notable changes in IAM 8.0 compared to IAM 7.7 are:
  • Deprecated features have been removed.
  • The JSP-Loginapp and all its related artifacts have been removed.
  • A database schema migration is mandatory.

To account for this special situation, several features have been implemented to support the migration process better.

Technical background on the update

Removing deprecated features, especially the JSP-Loginapp and its related features, result in a long list of removed plugins that are no longer part of IAM 8.0. For IAM 8.0 to run, the configuration must not contain any references to these no longer available plugins.

Thus, one of the challenges when upgrading is getting rid of all plugins that are no more supported.

  • To support this process, the following two features have been implemented:
  • IAM 7.7 Config Editor migration preparation support. See Preparing IAM 7.7 for upgrading to 8.0 (in IAM 7.7 Documentation).
  • Improved migration support in IAM 8.0: The configuration migration CLI (iam upgrade) has been improved to produce useful output supporting the migration preparation.

Prerequisites for upgrading

Prerequisite 1: This guide assumes that the JSP-Loginapp is no more used and the migration to the new Loginapp UI has already been done.

Further information on the loginapp migration can be found in Migrating from the JSP-Loginapp to the Loginapp REST UI (in IAM 7.7 documentation).

Prerequisite 2: Make sure not depending on removed features: go through the list of removed features. If depending on a feature removed in IAM 8.0, the dependency needs to be resolved before upgrading.

Prerequisite 3: Go through the list of actions required when upgrading and make sure all required actions are feasible when upgrading. The actions do not have to be performed before migrating the configuration (see below).

As for every update, it is strongly recommended to backup the IAM database and all IAM artifacts (configuration, UI customization, etc.) before starting the upgrade.

Step 1: Update to IAM 7.7

If you are not yet on IAM 7.7, it is recommended (but not required) to update to IAM 7.7.

  • There is no need to run IAM 7.7 when migrating via 7.7 to 8.0.
  • Just use the migration CLI iam upgrade to migrate the configuration XML.
  • If intending to use the above-mentioned Config Editor feature, it is sufficient to start a default IAM 7.7 (without custom configuration or other custom artifacts) just to be able to use the Config Editor. This can, for example, be achieved by installing IAM 7.7 and accessing the Adminapp (and from there the Config Editor) after resetting the configuration using the CLI command iam reset -i <instance-name>.
  • Usually (but not always) this also works with custom plugins (custom code) that have not been ported to be compatible with IAM 7.7: the Config Editor just needs to be able to load the plugins but not run them.

Step 2: Assure no removed features are configured

Before the IAM configuration can be migrated to IAM 8.0, it must be assured that the IAM 7.7 configuration does not configure features that have been removed.

  • To ensure this, do the following:
  • Go through list of removed features and make sure, the configuration does not configure removed features.
  • Especially make sure, all features relating to the JSP-Loginapp have been removed from the IAM 7.7 configuration: make sure all properties are emptied in Loginapp >> property group JSP Loginapp Settings. It is sufficient to disconnect the plugins, they don't have to be deleted.
  • As mentioned above, you may use the IAM 7.7 Config Editor support to ensure all discontinued plugins have been removed from the configuration (see Preparing IAM 7.7 for upgrading to 8.0 (in IAM 7.7 Documentation)).

Alternatively, you may just try to migrate the configuration as described in the following step: the migration CLI tells you if plugins are configured that are no more available.

Step 3: Migrate the configuration

Migrate the configuration using the migration CLI (for instance auth in the following example):

iam upgrade -i auth

The CLI will inform and abort if unsupported plugins are still part of the configuration to be migrated (see examples).

Example 1: upgrade command output for a configuration still containing a JSP-Loginapp configuration

> Applying changes for version "8.0"
>   FAIL: Ensure old JSP Loginapp properties are not configured before migrating 
>   "Authentication Settings" are configured that cannot be migrated automatically. Please remove this configuration and migrate to authentication flows as documented in the migration guide.
>   "Self-Service Settings" are configured that cannot be migrated automatically. Please remove this configuration and migrate to self-service flows as documented in the migration guide.

Example 2: upgrade command output listing plugins that are no more supported in IAM 8.0

> Applying changes for version "8.0"
>   PASS: Ensure old JSP Loginapp properties are not configured before migrating
>   PASS: Remove unsupported and unconnected JSP plugins
>   FAIL: Checks if deleted plugins are present in the configuration
>    Configuration contains plugins which have been deleted
>    Please replace these plugins before upgrading:
>     PLUGIN: Database Login History Repository (JSP)
>     PLUGIN:  Password Management Group Configuration
>     PLUGIN:  User Importer Task