How To

How do I perform a multi-server upgrade from OpenAM 10.x to a later version (Embedded configStore/ctsStore)?

Last updated Jan 5, 2021

The purpose of this article is to provide information on performing a multi-server upgrade from OpenAM 10.x to a later version (Embedded configuration store and CTS store). This is one of a series of articles intended to provide a known and tested methodology for upgrading OpenAM in a specific scenario. This procedure can be used as a reliable starting point for creating deployment-specific upgrade plans.


This article has been archived and is no longer maintained by ForgeRock.


Before performing this upgrade, you should read the Release Notes and Upgrade Guide applicable to the new release to improve your understanding of the upgrade process. In particular, you should refer to these sections (links provided for OpenAM 13):

If you are upgrading to OpenAM 13, you must ensure you are running the correct version of Java as per Java Requirements; OpenAM 13 does not function with Java 6.

You should also be aware of the following important changes that will occur as a result of this upgrade:

  • The token store between OpenAM 10.x and later releases is not compatible. If session persistence is in use, these sessions will be lost and users will need to re-authenticate when they next access the service.
  • There is a significant OpenDJ upgrade included. This upgrade occurs automatically during the first initialization of the new WAR file, not during the upgrade wizard.

Performing a multi-server upgrade

This is the simplest and safest method of upgrading. Use when you are able to have a downtime maintenance window where the service is inoperable. For a more advanced procedure with higher availability, please see the related articles linked below.

Where the term 'load balancer' is used, this simply means whichever balancing mechanism is used in the particular deployment. For example, physical/virtual load balancers, DNS round robin, reverse proxy etc.

Rollback plan

As per the Upgrade Guide, you will need to take a LDIF backup of the configuration data store in the directory servers as well as a file system backup.

You will need to take copies of:

  • The OpenAM instance directory (default ~/openam) while OpenAM is not running.
  • The web container with the deployed OpenAM, for example, /path/to/tomcat/webapps/openam for Apache Tomcat™.
  • The $HOME/.openamcfg/ directory of the user running the web application container where OpenAM is deployed.

Since OpenAM needs to be stopped to take the instance directory backup, the best time to take this is just after bringing down the instance. This also ensures the configuration is as up to date as possible.


  1. Disable all OpenAM instances from the load balancer. You can optionally set to show maintenance placeholder page if desired.
  2. Shut down all OpenAM servers.
  3. Take a backup on the first OpenAM instance, replace the WAR file and start the instance.
  4. Run through the OpenAM upgrade wizard.

If you are upgrading from OpenAM 10.1.0 Xpress, you must update the Dashboard service LDAP schema to complete the upgrade. This is detailed in the OpenAM Upgrade Guide › Upgrading OpenAM Servers › To Complete Upgrade from OpenAM 10.1.0 Xpress.

  1. Restart OpenAM and check for any issues with normal/expected operation. You can optionally bring this OpenAM instance back online straight away via your load balancer and observe normal operations.
  2. Take a backup of subsequent OpenAM instances in turn, replace the WAR file and start each one.
  3. Check the normal operation and replication status of the new installation. You can optionally re-add instances to the load balancer as desired or wait until all instances are upgraded and checked before re-adding them all at once.

See Also

Best practice for upgrading to OpenAM 13.x

Best practice for upgrading to OpenAM 12.x

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

How do I perform a high availability two-server upgrade from OpenAM 10.x to a later version (Embedded Configuration)?

How do I perform a high availability multi-server upgrade from OpenAM 10.x to a later version (Embedded Configuration)?

How do I upgrade AM (All versions) with minimal downtime when replication is used?

How do I upgrade AM 6.x if I am using a site configuration?

How do I make a backup of configuration data in AM 6.x?

FAQ: Upgrading AM

OpenAM 13 Release Notes

OpenAM 13 Upgrade Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-2110 (Upgrade fails if external configstore is using non-default user)

OPENAM-3173 (The dash.ldif contains bad order for the Upgrade from OpenAM 10.1.0 Xpress)

OPENAM-3192 (OpenAM 10 does not support OpenAM 11 schema)

OPENAM-3947 (Upgrade removes user-added Advanced Properties from Default Server Settings )

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.