This article has been archived and is no longer maintained by ForgeRock.
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.
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).
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:
- 11g server - java.lang.NoSuchMethodError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle WebLogic 11g server
- 12c server - java.lang.LinkageError: after upgrading to OpenAM 11.x or 12.x deployed on an Oracle® WebLogic 12c server
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