Best practice for upgrading to AM 7.x

Last updated Feb 24, 2021

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
Known issues - upgrade process
Known issues - post-upgrade
Other changes

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 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.

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

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.

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 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.

Related Training

ForgeRock Access Management Core Concepts (AM-400)

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)

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)