Preparing for Upgrade
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 AM 5.5 Release Notes, AM 5.1 Release Notes and AM 5 Release Notes so that you are fully aware of all changes as well as release notes and Best Practice upgrade articles relevant to any releases between the version you are upgrading from and AM 5.x.
You should ensure the following are true prior to upgrading:
- Anonymous access is permitted in DS/OpenDJ
- Referrals do not exist in the top level realm
Anonymous access is permitted in DS/OpenDJ
The upgrade is likely to fail if you have disabled anonymous access in DS/OpenDJ using the following command:
$ ./dsconfig --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:true --trustAll --no-prompt
See Upgrade to AM/OpenAM (All versions) fails when anonymous access is disabled in DS/OpenDJ for further information on this issue.
Referrals do not exist in the top level realm
Upgrading to AM 5.5.1 will fail if referrals exist in the top level realm, where URL patterns from the referral are being used in sub-realm policies; referrals were removed in OpenAM 13, so this issue will only affect you if you are upgrading from a pre-OpenAM 13 version.
If you have referrals in the top level realm, you should delete the referrals and policies prior to upgrade and then re-create the policies in the appropriate realms once you have upgraded.
This is a known issue: OPENAM-12120 (Referrals On Top Level Realm won't allow upgrade to 5.5.1).
Known issues - upgrade process
The following known issues may affect you during the upgrade process - workarounds are included where applicable:
- Configuration fails if you have an external user store in AM 5.5.x
- External CTS needs additional schemas after upgrade
- Custom authentication modules cannot be updated after upgrade
- Not found error when viewing authentication modules after upgrading to AM 5 or 5.1.x
Configuration fails if you have an external user store in AM 5.5.x
The Demo user should only be created in an embedded user store, but a known issue in AM 5.5.x causes the configurator or Amster to incorrectly attempt to create the Demo user in an external user store if the configuration store is embedded: OPENAM-11909 (Demo user creation is based on whether a userCfg is specified, rather than when it's set to embedded). This action causes the configuration to fail. You can workaround this issue by either configuring an embedded user store or by using an external configuration store with your external user store.
External CTS needs additional schemas after upgrade
When upgrading to AM 5.x from a previous version, you need to import the following schemas else you will not be able to log in:
See Installation Guide › CTS Installation Script for a sample install script that imports these schemas.
Custom authentication modules cannot be updated after upgrade
When upgrading to AM 5.x from OpenAM 12.x, there is a known issue which prevents custom authentication modules being updated. This is because schemas in the definition of an authentication service must now contain resourceName attributes. The necessary steps to resolve this are documented: OpenAM 13 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality; these can be performed before or after upgrading to AM 5.x. If you are upgrading from OpenAM 13.x, your schema will already be correct.
Not found error when viewing authentication modules after upgrading to AM 5 or 5.1.x
When upgrading to AM 5 or 5.1.x, there is a known issue that prevents access to authentication modules in the console if they have the same name and type: OPENAM-9156 ('Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type). See Creating authentication module via ssoadm causes Not found error in AM 5, 5.1.x and OpenAM 13.0, 13.5 for further information. This issue is resolved in AM 5.5.
You should also be aware of the following changes in behavior:
AM 5.x is not fully autonomous and crosstalk still occurs for SAML; this crosstalk should be eliminated in a future release. Similarly, policy agent sessions are held in memory rather than being stored in the CTS token store.
SSO tokens incompatibility: SSO tokens created in pre-AM 5 versions are not valid in AM 5, meaning users will need to reauthenticate once you have upgraded. See Upgrade Guide › About Upgrading › Supported Upgrade Paths for further information.
Clickjacking protection: The X-Frame-Options header is now set to SAMEORIGIN to prevent the page being framed by a malicious site. See FAQ: General AM/OpenAM (Q. How can I protect AM/OpenAM from Clickjacking?) for further information. This change may affect you if you have an existing application that uses frames.
Auto-generated OAuth2 policy (OAuth2ProviderPolicy) is no longer created in AM 5.5.x: When you configure AM/OpenAM as an OpenID Connect authorization server in AM 5.5.x, the default OAuth2ProviderPolicy is no longer created as it is not needed.
The server-only war file was removed in OpenAM 13: This was previously used to remove console access. You can still remove console access in AM 5.x as detailed in How do I remove console access in AM (All versions) and OpenAM 13.x?
See Release Notes › Important Changes to Existing Functionality for information about all changes to existing functionality.
Back Up and Restore
Upgrade Guides and Release Notes