Best practice for upgrading to AM 7.x
The purpose of this article is to provide best practice advice on upgrading to AM 7.x as there are some known issues regarding the upgrade process and issues that may affect you post-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 7 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 7.x.
Known issues - upgrade process
The following known issues may affect you during the upgrade process - workarounds are included where applicable:
- Configuring AM with an embedded DS fails with a Permission Denied error for the truststore
- Amster Configuration Upgrader tool is not included in AM
- External CTS needs additional schemas after upgrade
Configuring AM with an embedded DS fails with a Permission Denied error for the truststore
Configuring AM with an embedded DS fails when trying to create the truststore with a Permission Denied error. This is a known issue: OPENAM-16608 (AM with embedded DS setup fails with permission denied for truststore). You can workaround it by changing the file permissions on the origin cacerts file to have write permissions (for example, 666) before starting the configuration. This will ensure the resulting truststore file then has permissions 644 which allows setup to continue.
An embedded DS is not supported in production in AM 7, but you may still use one for testing or demo purposes.
Amster Configuration Upgrader tool is not included in AM
See How do I upgrade Amster configuration files when upgrading to AM 6.5.x or 7.x? for information on upgrading to AM 7.x if you have Amster configuration files.
When upgrading to AM 7.x from a previous version, you need to import the following schemas else you will not be able to log in:
- cts-add-multivalue.ldif
- cts-add-multivalue-indices.ldif
This step is detailed in the Upgrade Guide › Upgrading AM Instances.
Known issues - post-upgrade
The following known issues may affect you post-upgrade - workarounds are included where applicable:
- LDAP connection fails with No subject alternative DNS name matching error
- Login page does not load when using authentication trees with custom or Marketplace nodes
- Login page does not load or ssoadm fails after upgrading to Apache Tomcat™ 8.5 or 9
- Minimum password length is 8 error when updating identities via REST
- User attributes in SAML responses are not correctly mapped
LDAP connection fails with No subject alternative DNS name matching error
Changes in AM and DS have made LDAP SSL hostname validation stricter. You must ensure the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). See LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 5.5.2, 6.x, 7.x and DS 5.5.1, 5.5.2, 6.x, 7.x for further details about this issue and solution.
The dependency on forgerock-guava has been removed in AM 6.5 and instead these libraries are retrieved directly from Google Guava. Any custom or Marketplace nodes that uses one of the 'org.forgerock.guava' classes will fail as a result. See Login page does not load when using authentication trees with custom or Marketplace nodes in AM 6.5.x or 7.x for further information.
Login page does not load or ssoadm fails after upgrading to Tomcat 8.5 or 9
Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9
Minimum password length is 8 error when updating identities via REST
There is a known issue with updating identities via REST where the "Minimum password length is 8" error is shown even though the user's password is valid: OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API). The necessary steps to resolve this are documented in the following Solution article: Minimum password length is 8 error in AM (All versions) when updating identities using the REST API
User attributes in SAML responses are not correctly mapped
There is a known issue that can prevent user profile attributes being returned in SAML responses. This issue occurs if use a custom IdP attribute mapper that extends DefaultLibraryIDPAttributeMapper: OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade). You should revisit your custom IdP mapper code and update any method names that have changed. Alternatively, you could extend DefaultIDPAttributeMapper instead. This class is available from the OpenFM-7.x.x.jar file located in the WEB-INF/lib directory of the AM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.
Other changes
See Release Notes › Changes to Existing Functionality for information about all changes to existing functionality.
See Also
Upgrades
- Upgrade Guide › Supported Upgrade Paths
- FAQ: Upgrading AM/OpenAM
- How do I upgrade AM/OpenAM (All versions) with minimal downtime when replication is used?
- Upgrading AM/OpenAM
Back Up and Restore
Upgrade Guides and Release Notes
- How do I enable message level debugging for install and upgrade issues with AM/OpenAM (All versions)?
- How do I record troubleshooting information in AM/OpenAM (All versions)?
- Best practice for recording troubleshooting information in AM/OpenAM (All versions)
- Troubleshooting AM/OpenAM and Agents
- ForgeRock Production Event Guidance/Checklist
- Best practice for raising a ticket with ForgeRock Support
Related Training
Related Issue Tracker IDs
OPENAM-16608 (AM with embedded DS setup fails with permission denied for truststore)
OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)