Best Practice
Archived

Best practice for upgrading to OpenAM 12.x

Last updated Jan 5, 2021

The purpose of this article is to provide best practice advice on upgrading to OpenAM 12.x as there are some known issues regarding the upgrade process.


2 readers recommend this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Preparation

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the OpenAM Release Notes relating to the new version of OpenAM so that you are fully aware of all the changes. 

You should ensure the following are true prior to upgrading:

  • Anonymous access is permitted in OpenDJ
  • Referral rules are correct
  • Policy and rule names are valid

Anonymous access is permitted in OpenDJ

The upgrade is likely to fail if you have disabled anonymous access in OpenDJ using the following command:

$ ./dsconfig -p [adminport] -h [hostname] -D "cn=Directory Manager" -w [password] set-global-configuration-prop -X -n --set reject-unauthenticated-requests:true

where [adminport], [hostname] and [password] are specific to your environment.

See Upgrade to AM 5.x or 6.x fails when anonymous access is disabled in DS for further information on this issue.

Referral rules are correct

You should have three referral rules from the top-level realm as per changes that were introduced in OpenAM 11.0.0. Neglecting to have three referral rules will cause your upgrade to fail as detailed in Upgrade to OpenAM 13.x fails with Failed to modify privilege! message when migrating policies.

You should have three referral rules as follows: 

  • root "/"
  • pages "/*"
  • pages with parameters "/*?*"

See Best practice for creating and testing policies in AM (All versions) for further information on creating and testing policies in OpenAM 12.x.

Policy and rule names are valid

OpenAM 12.0.0 introduces a new policy engine and policy editor, which means policies are migrated as part of the upgrade process when upgrading to OpenAM 12.x. You need to ensure that rule names don't include forward slashes and rule / policy names don't include special characters.

See Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x for further information on policies being migrated and the steps you can take to ensure it is successful.

Known issues

The following issues are known regarding the upgrade process, including workarounds where applicable:

  • Upgrade hangs when configuration and CTS stores are external
  • Upgrade fails when CTS store is external and has a non-default suffix
  • CTS port settings revert to default
  • OAuth client configurations inherit default response types
  • Oracle® WebLogic class file conflict

Upgrade hangs when configuration and CTS stores are external

When upgrading to OpenAM 12.x, the upgrade may hang because the default connection pool sizing of 10 is too small. This is a known issue, which is fixed in OpenAM 12.0.2: OPENAM-6456 (Upgrading to OpenAM 12 hangs in DirectoryContentUpgrader).

See Upgrade to OpenAM 12.0.0 or 12.0.1 hangs in DirectoryContentUpgrader when configuration and CTS stores are external for further information and a workaround to resolve this issue.

Upgrade fails when CTS store is external and has a non-default suffix

When upgrading to OpenAM 12.x, the upgrade may fail because OpenAM looks up the default suffix for the external CTS store and then tries to create it even though it does exist (but as a different suffix). This is a known issue, which is fixed in OpenAM 12.0.2: OPENAM-6457 (DirectoryContentUpgrader causes Entry Already Exists exception for CTS suffix when upgrading OpenAM).

See Upgrade to OpenAM 12.0.0 or 12.0.1 fails with Entry Already Exists exception when CTS store is external with non-default suffix for further information.

CTS port settings revert to default

When upgrading to OpenAM 12.0.0, the CTS port settings revert to 389. You should check and correct your CTS port settings if they should be anything other than 389. This is a known issue, which is fixed in OpenAM 12.0.1: OPENAM-5183 (CTS port settings are reverted to default when doing upgrade from AM 11 to AM 12).

OAuth client configurations inherit default response types

When upgrading from OpenAM 11.x, there is a known issue OPENAM-4076 (Upgrade 11.x->12 cannot successfully migrate configured OAuth2 clients) which causes OAuth client configurations to inherit default response types. The necessary post-upgrade steps to resolve this are documented in the Upgrade guide: To Complete Upgrade from OpenAM 11.0.

Oracle WebLogic class file conflict

If you use an Oracle WebLogic server, you may experience a class file conflict depending on which version of OpenAM you have come from (pre-OpenAM 11.0.0 only) and the version of Oracle WebLogic you are running. The following Solution articles outline the issues you may experience depending on your Oracle WebLogic version:

Upgrade to OpenAM 12.0.x or 13.x fails with Failed to modify privilege! when migrating policies

When upgrading from a pre-OpenAM 12.0.0 release, there is a known issue OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails) that will only occur if the policies are being migrated to the OpenAM 12.x or 13.x format for the first time. The necessary steps to resolve this are documented in the following Solution article  Upgrade to OpenAM 13.x fails with Failed to modify privilege! message when migrating policies

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x 

OpenAM 13 login fails with User name/password combination is invalid error if you use host-based cookies

How do I upgrade AM (All versions) with minimal downtime when replication is used?

How do I enable message level debugging for install and upgrade issues with AM (All versions)?

FAQ: Upgrading AM

OpenAM 12 Upgrade Guide

OpenAM 12.0.4 Release Notes

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3498 (IdRepo connection pool fails if anonymous access is disabled)

OPENAM-4076 (Upgrade 11.x->12 cannot successfully migrate configured OAuth2 clients)

OPENAM-5183 (CTS port settings are reverted to default when doing upgrade from AM 11 to AM 12)

OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service)

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-6455 (ConnectionCount logic does not produce a sensible ConnectionFactory max pool size for some scenarios)

OPENAM-6456 (Upgrading to OpenAM 12 hangs in DirectoryContentUpgrader)

OPENAM-6457 (DirectoryContentUpgrader causes Entry Already Exists exception for CTS suffix when upgrading OpenAM)

OPENAM-6499 (Configuration store servers are not listed in Directory Configuration)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.