PingAM 8.0.1

Plan the upgrade

The work involved in upgrading AM software depends on the magnitude of change between your current version and the new version:

  • Maintenance releases have a limited effect on current functionality but contain necessary bug and security fixes. Keep up to date with maintenance releases, as the fixes are important and the risk of affecting service is minimal.

  • When upgrading to a new major or minor release, always plan and test the changes before carrying out the upgrade in production. Make sure you read the Release notes for intervening versions with care. Identify any changes likely to affect your deployment and then plan accordingly.

Authentication modules and chains have been removed in AM 8.0. If you’re still using modules and chains for authentication, you must migrate to nodes and trees as soon as possible.

It’s recommended that you migrate to nodes and trees before upgrading to AM 8.

If that’s not possible, and you need access to modules and chains for migration purposes, you can temporarily re-enable modules and chains in AM 8.0.

Re-enable modules and chains

  1. Go to Configure > Server Defaults > Advanced in the AM admin UI.

  2. Add the org.forgerock.am.authentication.chains.enabled property and set it to true.

  3. Save your changes.

  4. Restart AM or the container where it runs.

You can now access modules and chains through the REST endpoints. Modules and chains aren’t accessible through the AM admin UI.

The option to re-enable modules and chains is only for migration purposes in AM 8.0. Authentication modules and chains will be removed completely in an upcoming release.

Review the following best practices before you upgrade AM:

Route around servers during downtime

Upgrading servers takes at least one of your AM sites down while you update the server configurations to the new version. Plan for this site to be down. Route client applications to another site until the upgrade process is complete, and you have validated the result. Make sure client application owners are aware of the change, and let them know what to expect.

If you only have a single AM site, make sure the downtime happens in a low-usage window, and make sure you let client application owners plan accordingly.

During an upgrade, restrict access to the AM admin UI. The Upgrade Wizard doesn’t require authorization. Immediately after you deploy the new .war file, any user with access to the AM admin UI can start the upgrade process.

Back up the deployment

Always back up your deployment before you upgrade. If something goes wrong during the upgrade process, you can then roll back to the previous version.

  • In production environments, back up your configuration as described in Back up configurations.

  • In preparation for upgrading AM servers and their configurations, also take LDIF backups of the configuration store data in the directory servers. If possible, stop servers before upgrading and take a file system backup of the deployed servers and also of their configuration directories. This can make it easier to roll back from a failed upgrade.

    For example, if you deploy AM in Apache Tomcat under /am, you might take a file system backup of the following directories for each AM server:

    • /

    • ~/am/

    • ~/.openamcfg/

  • When upgrading tools, keep copies of any customized scripts.

  • Back up the key stores and trust stores you use to connect securely.

  • Record any custom advanced server properties configured under Configure > Server Defaults > Advanced or Deployment > Servers > Server Name > Advanced in the AM admin UI. These properties are lost during the upgrade and must be re-added after the upgrade is complete.

Review REST API versions before upgrading

Upgrading AM can update the default API version of several AM endpoints. After an upgrade, your applications might experience issues connecting to endpoints if they don’t specify the API version in REST calls.

By default, an upgraded AM instance responds to REST calls that don’t specify version information with the oldest version available for the endpoint. However, the oldest supported version might not be the one required by the application, as API versions become deprecated or unsupported.

To avoid version conflicts between application calls and REST endpoint APIs, consider specifying the protocol and resource version required by the application in the Accept-API-Version header when making requests to REST endpoints. Learn more in Specify REST API versions.

AM includes a CSRF protection filter that’s enabled by default. REST requests other than GET, HEAD, and OPTIONS made to endpoints under the json/ root return 403 Forbidden messages unless they include the X-Requested-With or Accept-API-Version headers.

Learn more in Protect against CSRF attacks.

You can configure AM’s default REST API behavior. Learn more in Configure versioning behavior.

Review PingDS certificates before upgrading

Before you upgrade, review the certificates used to establish secure connections between AM and the DS stores.

If the FQDN value from the subject field of a non-wildcard certificate doesn’t match the FQDN obtained from DNS for the DS instance, AM can’t establish a secure connection with DS. Additionally, if the DS instance responds to multiple FQDNs, you must also specify them in the certificate.

This step is critical for the configuration store. If AM can’t establish communication with the configuration store, it fails to start up.

You can find more information about setting up DS server certificates in Key management in the DS documentation.

Customize before upgrading

Prepare a .war file that contains any customizations you require.

Customizations include any changes you’ve made to the AM server installation, such as the following:

  • Custom plugins and extensions, for example:

    • Custom authentication nodes.

    • Custom SAML v2.0 attribute mappers.

    • Custom OAuth 2.0 scope validators.

    New functionality often changes the samples provided with AM.

    Don’t copy custom plugins or extensions from a previous version of AM to the .war file.

    You must customize the samples of the version you’re upgrading to before adding them to the .war file. For example, download the custom scope validator sample of the version you’re upgrading to, customize it, recompile it, then add the resulting .jar file to the .war file.

    Failure to use the new version’s samples as the base for your customizations can result in unexpected behavior.

  • Customized JSPs, redesigned login or service pages and additional CSS and visual content.

  • Any changes to AM classes or APIs.

    Recompile any custom implementations you have created with each release of AM, because the method signature or imports for supported and evolving APIs can change in each version.

  • Any changes or additional Java class libraries (such as .jar files in WEB-INF/lib ).

Plan for rollback

Sometimes even a well-planned upgrade operation fails. In such cases, you need a plan to roll back to the pre-upgrade version.

For AM servers, you can roll back by restoring from a file system backup. Restore the old configuration directory service from LDIF before you restart the old servers. Learn more in Back up configurations.

If you upgraded using the upgrade wizard and need to roll back the upgrade to a version earlier than AM 7.4, you must restore the default keystore. The upgrade wizard removes a default alias that AM versions before AM 7.4 need to start. If you don’t restore this alias, the rolled back instance of AM won’t start up.

Upgrade in a test environment first

Always try upgrading AM in a test environment before applying the upgrade in your production environment.

This helps you assess the volume of work required without affecting your production environment, and can circumvent unforeseen problems.