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.
Overview
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 7.2 Release notes, AM 7.1 Release Notes and 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
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), which is fixed in AM 7.0.2. You can work around 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 can still use one for testing or demo purposes.
- Amster Configuration Upgrader tool is not included in AM 7
See How do I upgrade Amster configuration files when upgrading to AM 6.5.x or 7? for information on upgrading to AM 7 if you have Amster configuration files.
AM 7.1 does include a configuration file upgrade tool for converting configuration files exported with the Amster command. See Amster 7.1 What’s New for further information.
- External CTS needs additional schemas after upgrade
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
- cts-add-ttlexpire.ldif
This step is detailed in the 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
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 and DS (All versions) for further details about this issue and solution.
- Login page does not load when using authentication trees with custom or Marketplace nodes
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 use an org.forgerock.guava class 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 you 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 or implement an IdP attribute mapper using a script (AM 7.2 and later). See How do I create a custom SAML2 IdP attribute mapper in AM (All versions)? for further information.
Other changes
See AM 7.2 Functional changes, AM 7.1 Changes to Existing Functionality and AM 7 Changes to Existing Functionality for information about all changes to existing functionality.
See Also
Upgrades
- Supported Upgrade Paths
- FAQ: Upgrading AM
- How do I upgrade AM (All versions) with minimal downtime when replication is used?
- Upgrading AM
Backup and Restore
Upgrade Guides and Release Notes
- AM 7.2 Release notes
- AM 7.2 Upgrade
- AM 7.1 Release Notes
- AM 7.1 Upgrade
- AM 7 Release Notes
- AM 7 Upgrade
Troubleshooting
- How do I enable message level debugging for install and upgrade issues with AM (All versions)?
- How do I record troubleshooting information in AM (All versions)?
- Troubleshooting AM and Agents
- ForgeRock Production Event Guidance/Checklist
- Best practice for raising an Identity Platform ticket with ForgeRock Support
Related Training
ForgeRock Access Management Deep Dive (AM-410)
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)