Untitled | PingAM 7.5.1

Upgrade

This guide covers common aspects of upgrading an AM deployment, whether you are moving to a new maintenance release, upgrading to a new major release, or migrating from a legacy release to a newer AM release.

Release levels, and how much change to expect in a maintenance, minor, or major release, are defined in Product Release Levels. Release levels are identified by version number.

AM supports several versions of the web and Java agents, so you don’t usually need to upgrade your agents when you upgrade AM.

You can find information on the supported AM versions in Web Agents or Java Agents.

Learn more about upgrading web and Java agents in the Web Agents documentation or the Java Agents documentation.

Before you upgrade

Review the tasks you need to complete before upgrading AM.

Upgrading servers

Learn, step by step, how to upgrade the AM core services.

Upgrading components

Review components and services that you might need to upgrade or reconfigure.

Name changes for ForgeRock products

Product names changed when ForgeRock became part of Ping Identity.

The following name changes have been in effect since early 2024:

Old name	New name
ForgeRock Identity Cloud	PingOne Advanced Identity Cloud
ForgeRock Access Management	PingAM
ForgeRock Directory Services	PingDS
ForgeRock Identity Management	PingIDM
ForgeRock Identity Gateway	PingGateway

Old name

New name

ForgeRock Identity Cloud

PingOne Advanced Identity Cloud

ForgeRock Access Management

PingAM

ForgeRock Directory Services

PingDS

ForgeRock Identity Management

PingIDM

ForgeRock Identity Gateway

PingGateway

Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.

Supported upgrade paths

This table contains information about the supported upgrade paths to AM 7.5:

Upgrade paths
Version	Upgrade Supported?
AM 6.5.x ⁽¹⁾	✔
AM 7.x	✔

⁽¹⁾ AM 6.5.x is an unsupported version of AM but the upgrade path is currently supported.

If you are upgrading from any other unsupported versions of AM to a later version, you must first upgrade to a supported version. In some cases, you may need to upgrade again depending on the upgrade path.

Learn more in the Ping Identity Product Support Lifecycle Policy in the Knowledge Base.

The embedded DS server is not supported for production in AM 7.5. If you have an existing site configured with embedded DS, you must migrate it to an external DS store before upgrading to AM 7.5.

The embedded DS was deprecated in AM 7, and will be removed in a future release.

How do I know if my deployment uses the embedded DS?

(AM 6 or earlier) Go to Deployment > Servers > Server Name > Advanced, and check the value of the com.sun.identity.sm.sms_object_class_name advanced property.

If the value is com.sun.identity.sm.ldap.SMSEmbeddedLdapObject, the server is an evaluation instance of AM, and is using an embedded DS instance as the configuration store.
In the server where AM is installed, check if the opends directory exists under the /path/to/openam directory.

You may have migrated it to an external directory and not deleted the directory, though. Check the files in the opends/logs directory to determine if the embedded DS is running.
Go to Deployment > Servers > Server Name > Directory Configuration > Server, and check the value of the host name column.

When using an external configuration store, the AM instances point to the FQDN of the load balancer in front of the DS cluster, or to the FQDN of the DS affinity deployment.

When using an embedded configuration store, each AM instance points to its own hostname, since the embedded DS is stored alongside the AM instance.

Use either of the following methods to migrate an embedded data store to an external store before attempting to upgrade to AM 7.5:

Migrate data to an external instance of DS by using LDIF files.

Follow the steps in How do I migrate from an embedded to external DS in AM 6.5? in the Knowledge Base.
Add a new external DS instance and replicate data from the embedded instance.

See When Adding New Servers in the DS documentation.

Plan the upgrade

How much you must do to upgrade AM software depends on the magnitude of the differences between the version you currently use 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.

Review the following best practices before you upgrade AM:

Route around servers during downtime
Back up the deployment
Review REST API versions before upgrading
Review PingDS certificates before upgrading
Customize before upgrading
Plan for rollback
Upgrade in a test environment first

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 well 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 console: The Upgrade Wizard page doesn’t require authorization; any user with access to the AM admin UI immediately after you deploy the new WAR file can therefore 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 as well. This can make it easier to roll back from a failed upgrade.

For example, if you deploy AM server in Apache Tomcat under /openam, you might take a file system backup of the following directories for each AM server.
- /path/to/tomcat/webapps/openam/
- ~/openam/
- ~/.openamcfg/
When upgrading tools, keep copies of any scripts you’ve edited for your deployment.
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 may update the default API version of several AM endpoints. After an upgrade, your applications may experience issues connecting to endpoints if they don’t specify API version information 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 may 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. For details, refer to Specify REST API versions.

From version 6, 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 will return 403 Forbidden messages unless they include the X-Requested-With or Accept-API-Version headers.

For details, refer to Protect against CSRF attacks.

You can configure AM’s default REST API behavior. For details, refer to 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 cannot establish communication with the configuration store, it will fail to start up.

For more information about setting up DS server certificates, refer to Key management in the DS documentation.

Customize before upgrading

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

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

Custom plugin and extensions, for example:

Custom authentication modules.
Custom authentication nodes.
Post-authentication plugins.
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, and then add the resulting .jar file to the .war file.

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

Customized JSPs, redesigned login or service pages, additional CSS and visual content, and modified authentication module callback files.
Any changes to AM classes or APIs.

Recompile any custom implementations you have created with each release of AM, as 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 file system backup. If you use an external configuration directory service, restore the old configuration from LDIF before you restart the old servers. For details, refer to Back up configurations.

If you upgraded using the upgrade wizard and need to roll back the upgrade, 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.

Upgrade AM instances

To upgrade an AM deployment, you must upgrade each server instance in your site. This is achieved by upgrading the AM server software on each server. However, you only need to upgrade the configuration on one server in the site.

High-level upgrade steps

Upgrading AM involves the following high-level steps:

On one server in your site:
1. Deploy the new AM .war file and restart the server.
2. Upgrade the configuration.
3. Restart the server.
On the remaining servers in your site:
1. Deploy the new AM .war file and restart the server.

For older AM versions, you might not be able to upgrade directly to AM 7.5. Learn more in Supported upgrade paths.

Upgrade the following elements of an AM instance:

AM server software

The server is upgraded when you deploy the .war file of the new version. You must deploy the new .war file to each server in the site.

Configuration

Use one of the following methods to upgrade the configuration:

amupgrade

This utility is provided in the AM-7.5.1.zip file and upgrades a configuration exported using Amster. This is the recommended way to update the configuration.
Upgrade wizard

The upgrade wizard is launched when you replace a deployed AM .war file with a newer version, then go to the deployment URL.
openam-upgrade-tool

The openam-upgrade-tool-14.1.3.28.jar is installed when you set up the configuration tools.

You cannot upgrade the configuration by deploying a new version and then using ssoadm import-svc-config to import an existing configuration.

Schema

Generally, the configuration store schema is updated when you update the configuration. From time to time, updates are required to the schema of other data stores, such as the identity store, or the CTS store. These updates must be made manually.

Refer to Update the schema for more information.

Tools and scripts

Read the Release notes to understand the changes introduced in each version before you upgrade AM tools and scripts.

The embedded PingDS (DS) server is not supported in production from AM 7 onwards.

If you have an existing site that uses an embedded DS, you must migrate it to an external DS store before you upgrade to AM 7.x.

The embedded DS was deprecated in AM 7 and will be removed in a future release.

How do I know if my deployment uses the embedded DS?

(AM 6 or earlier) Go to Deployment > Servers > Server Name > Advanced, and check the value of the com.sun.identity.sm.sms_object_class_name advanced property.

If the value is com.sun.identity.sm.ldap.SMSEmbeddedLdapObject, the server is an evaluation instance of AM, and is using an embedded DS instance as the configuration store.
In the server where AM is installed, check if the opends directory exists under the /path/to/openam directory.

You may have migrated it to an external directory and not deleted the directory, though. Check the files in the opends/logs directory to determine if the embedded DS is running.
Go to Deployment > Servers > Server Name > Directory Configuration > Server, and check the value of the host name column.

When using an external configuration store, the AM instances point to the FQDN of the load balancer in front of the DS cluster, or to the FQDN of the DS affinity deployment.

When using an embedded configuration store, each AM instance points to its own hostname, since the embedded DS is stored alongside the AM instance.

Use either of the following methods to migrate an embedded DS to an external DS before you upgrade AM:

Migrate data to an external DS instance by using LDIF files.

Follow the steps in How do I migrate from an embedded to external DS in AM 6.5? in the Knowledge Base.
Add a new external DS instance and replicate data from the embedded instance.

Follow the steps in When adding new servers in the DS documentation.

Before you upgrade

You must follow these steps before you start an upgrade.

Plan your upgrade.
Prepare a customized AM .war file.
Back up your deployment.
Route client application traffic to another site during the upgrade.
Make the secure state encryption key available to all instances in the site.

An AES 256-bit key called directenctest must be available to all instances in the site. This might mean, for example, copying the keystore across the site.

This key does not need to be the same key that AM provides in the default keystore.

If you don’t provide this key, AM will not start up after the upgrade.

What is the directenctest key for?

AM uses the directenctest key to encrypt information stored in the secure state of authentication trees. This encryption is a mandatory feature of the trees from AM 7 onwards.

The upgrade process maps this key to the am.authn.trees.transientstate.encryption secret label.
How do I make the directenctest key available?
- If you’re upgrading from a version of AM earlier than 6.5:
  
  The key alias must exist in the keystore configured as the AM keystore. Check the path where the keystore and its files are configured by going to Configure > Server Defaults > Security > Key Store.
- If you’re upgrading from AM 6.5 or later:
  
  The alias must exist in a secret store configured globally, so that all realms can access it. You can configure additional secrets by realm, if required, after the upgrade.
  
  You can create a new secret store to house this secret, or you can add it to one of your existing stores.
  
  The following example creates the key alias in the AM keystore, or in a keystore configured in a secret store:
  
  $ keytool \ -genseckey \ -alias directenctest \ -keyalg AES \ -keysize 256 \ -storetype JCEKS \ -keystore /path/to/keystore.jceks
Where do I find the keystore passwords?
- (AM versions earlier than 6.5) The passwords are stored in the files configured in Configure > Server Defaults > Security > Key Store.
- (AM 6.5) The passwords are secrets provided by a different secret store. For example, a file system volume secret store.
After the upgrade, you can rename the key alias or set a different key in the secret label mapping. Make sure the secret label is always mapped to an existing, resolvable secret or key alias.

Upgrade the server and configuration

Use one of the following methods to upgrade the AM server software and configuration:

`amupgrade`

The amupgrade utility converts a set of exported AM configuration files so that the configuration can be used with the latest AM version. Use this utility with Amster and to upgrade file-based configurations (from version 7.0 onwards). The utility has the same Java requirements as Amster. Refer to the Amster Release notes for more information.

Upgrade paths with `amupgrade`

You can use amupgrade to upgrade the following versions of a configuration exported with Amster:

Upgrade from	Upgrade to
5.0, 5.1	5.5
5.5	6.0
6.0.x	6.5
6.5.x	7.0.x
7.0.x	7.1.x, 7.2.x, 7.3.x, 7.4.x, 7.5.x
7.1.x	7.2.x, 7.3.x, 7.4.x, 7.5.x
7.2.x	7.3.x, 7.4.x, 7.5.x
7.3.x	7.4.x, 7.5.x

Upgrade from

Upgrade to

5.0, 5.1

5.5

6.0

6.0.x

6.5

6.5.x

7.0.x

7.1.x, 7.2.x, 7.3.x, 7.4.x, 7.5.x

7.1.x

7.2.x, 7.3.x, 7.4.x, 7.5.x

7.2.x

7.3.x, 7.4.x, 7.5.x

7.3.x

7.4.x, 7.5.x

You cannot use amupgrade to upgrade a running AM instance.

Before you start

Download the AM .zip file from the BackStage download site.
Extract the contents of the .zip file.
In the extracted openam directory, locate the Config-Upgrader-7.5.zip file.
Extract the Config-Upgrader-7.5.zip file.

Upgrade from an `Amster` configuration export

Follow the Amster documentation to export your configuration.
Upgrade the exported configuration to the new version:
```
$ amupgrade \
-i exported configuration \
-o output directory \
-a amster version \
rules/amster/from-to-to.groovy
```
Where:
- exported configuration is the path to the configuration directory you generated in step 1
- output directory is the directory to which the command writes the upgraded configuration
- amster version is the version of Amster you will use to import the configuration
- from is the AM version from which you’re upgrading
- to is the AM version to which you’re upgrading
- rules specifies the path to a configuration rules file in the /path/to/amupgrade/rules directory
For example:
$ amupgrade \ -i /path/to/AM7.3Config/ \ -o /path/to/AM7.5Config \ -a 7.5 \ rules/amster/7.3.x-to-7.5.x.groovy Reading existing configuration from files in /path/to/AM7.3-config/… Modifying configuration based on rules in [rules/amster/7.3.x-to-7.5.x.groovy]… reading configuration from Amster json files Writing configuration to new location at /path/to/AM7.5Config… Upgrade Completed, modified configuration saved to /path/to/AM7.5Config
If you are upgrading a file-based configuration, rather than a configuration exported with Amster, use the --fileBasedMode option instead of the -i and -o options.
Install a new version of DS with an am-config profile.

Don’t upgrade or use an existing DS configuration store because configuration associated with the older DS version can cause conflicts.
Stop AM or the container where it runs.
Undeploy the AM web application.

For example, if you are using Apache Tomcat as the web container, remove the .war file and expanded web application from the container:
```
$ cd /path/to/tomcat/webapps/
$ rm -rf openam.war openam/
```
Install the new version of AM using the new DS server for your configuration store.
Follow the Amster documentation to import the upgraded configuration.
Restart AM or the container where it runs.

Upgrade wizard

The upgrade wizard brings the AM configuration, including the version number, up to date with the new version.

Stop AM or the container where it runs.
Deploy your customized AM .war file.

When you deploy the new .war file, you might need to delete working files left by the old deployment.

For example, if you deploy on Apache Tomcat, replace /path/to/tomcat/webapps/openam.war with the customized .war file, then recursively delete the /path/to/tomcat/webapps/openam/ and /path/to/tomcat/work/Catalina/localhost/openam/ directories before restarting the server.
Restart AM or the container where it runs.
After deploying AM, but before upgrading, your application container serves AM’s upgrader user interface.

Suspend any external network access to the application container until the upgrade is complete. After the upgrade is complete, AM prevents access to the upgrader UI.
Go to the deployment URL and follow the prompts to upgrade.
Restart AM or the container where it runs.
Update the identity store schema:
1. Log into AM.
2. Go to Realms > Realm Name > Datastores > External User Store.
3. Click Load Schema then click Save to apply your changes.
4. If you have additional identity stores, repeat the previous steps for each store.

The AM upgrade wizard uses three libraries that should be removed after upgrade, for security reasons.
When your upgrade is complete, remove the following .jar files from the WEB-INF/lib directory:
- click-extras-2.3.0.jar
- click-nodeps-2.3.0.jar
- velocity-1.7.jar
These files are used only by the install and upgrade wizards. Removing them will have no effect on your installed instance.

You must also remove the references to click-servlet from the deployment descriptor file. Edit /path/to/openam/WEB-INF/web.xml to remove the following mappings:
<servlet> <servlet-name>click-servlet</servlet-name> <servlet-class>org.apache.click.ClickServlet</servlet-class> </servlet> ... <servlet-mapping> <servlet-name>click-servlet</servlet-name> <url-pattern>*.htm</url-pattern> </servlet-mapping>

`openam-upgrade-tool`

The openam-upgrade-tool lets you upgrade the configuration without user intervention.

Stop AM or the container where it runs.
Deploy your customized AM .war file.

When you deploy the new .war file, you might need to delete working files left by the old deployment.

For example, if you deploy on Apache Tomcat, replace /path/to/tomcat/webapps/openam.war with the customized .war file, then recursively delete the /path/to/tomcat/webapps/openam/ and /path/to/tomcat/work/Catalina/localhost/openam/ directories before restarting the server.
Restart AM or the container where it runs.
Set up the configuration tools to install the openam-upgrade-tool-14.1.3.28.jar.

A sampleupgrade file is expanded in the directory where you install the tool.
Create a configuration file, for example, upgrade.properties.

You can use the sampleupgrade file as a template.

The upgrade configuration file should resemble the following:
```
$ grep -v "^#" upgrade.properties
SERVER_URL=https://openam.example.com:8443
DEPLOYMENT_URI=/openam
ACCEPT_LICENSES=true
```

Run the upgrade tool, specifying the upgrade.properties file you created:

$ java -jar openam-upgrade-tool-14.1.3.28.jar --file upgrade.properties
Writing Backup; Done.
Upgrading Services
New service iPlanetAMAuthPersistentCookieService; Done.
New service iPlanetAMAuthOpenIdConnectService; Done.
New service OAuth2Provider; Done.
New service iPlanetAMAuthDevicePrintModuleService; Done.
New service crestPolicyService; Done.
New service RestSecurity; Done.
New service MailServer; Done.
New service dashboardService; Done.
New service iPlanetAMAuthOATHService; Done.
Add Organization schema to sunFAMSAML2Configuration; Done.
Upgrade sunAMAuthHOTPService; Done.
Upgrade sunAMAuthADService; Done.
Upgrade sunAMAuthOAuthService; Done.
Upgrade iPlanetAMAuthCertService; Done.
Upgrade sunIdentityRepositoryService; Done.
Upgrade iPlanetAMPasswordResetService; Done.
Upgrade iPlanetAMSessionService; Done.
Upgrade iPlanetAMAuthService; Done.
Upgrade iPlanetAMAuthLDAPService; Done.
Upgrade sunAMAuthDataStoreService; Done.
Upgrade AgentService; Done.
New sub schema sunIdentityRepositoryService; Done.
New sub schema AgentService; Done.
Delete service sunFAMLibertyInteractionService; Done.
Delete service sunFAMLibertySecurityService; Done.
Creating entitlement application type crestPolicyService; Done.
Creating entitlement application crestPolicyService; Done.
Re-enabling Generic LDAPv3 Data Store; Done.
Upgrading data store embedded; Done.
Updating Platform Properties; Done.
Writing Upgrade Log; Done.

Upgrade Complete.

For more information about openam-upgrade-tool-14.1.3.28.jar, refer to the reference documentation.

Restart AM or the container where it runs.

Update tools, scripts, and components

Update the AM tools.

Follow Set up administration tools and the Amster User Guide to install an updated version of the tools.

When you have confirmed that the new tools are working, delete the old tools.
Make sure the AM scripts are current and contain the modifications your environment requires.

To avoid overwriting changes made in customized scripts, the upgrade process does not update scripts from earlier versions of AM.

Check that the scripts in your environment are compatible with the version of AM you’re upgrading to by following these steps:
1. Read the Release notes for information about possible changes.
2. Install an AM 7.5 test environment, and compare the scripts.
  
  New installations always have the current scripts.

Review the information in Upgrade components and services and decide if you need to reconfigure any of AM’s services or features.

Reconfigure any custom advanced properties if necessary. These properties are lost during the upgrade, and you will need to add them again in the AM admin UI.

How do I configure advanced server properties?

To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI.
To configure advanced server properties for a particular instance, go to Deployment > Servers > Server Name > Advanced.

If the property you want to add or edit is already configured, click on the pencil () button to edit it. When you are finished, click on the tick () button.

Click Save Changes.

Update the schema

You might need to update the schema for specific data stores, depending on the version from which you are upgrading and the data store type.

Configuration store

Generally, updating your configuration will also make the required schema updates to the configuration store.

After you have updated the configuration, add an access control instruction (ACI) to the configuration store directory to give the AM administrative user server-side sorting privileges.

The ACI should be similar to the following:

aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;
acl "Allow server-side sorting"; allow (read)
 (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)

Refer to Prepare configuration stores for more information about configuring AM configuration stores.

Identity store

Depending on the version you are upgrading from, and the features you have configured, you might need to update your identity store schema manually.

Upgrade from a version prior to 6.0 with knowledge-based (KBA) user self-service questions

You must apply this update if you added the user_store_type_kba.ldif schema to your external user data store, even if you did not configure user self-service.

In the path where you deployed the openam.war file (for example, /path/to/tomcat/webapps/openam) locate the following files in the WEB-INF/template/ldif/opendj directory:
- opendj_add_kba_attempts.ldif
- opendj_update_aci_kba_attempts.ldif
If your user data store is not PingDS, use these files as examples to create LDIF files suitable for your environment.
In the opendj_update_aci_kba_attempts.ldif file, replace @SM_CONFIG_ROOT_SUFFIX with the base DN you defined when you installed DS (for example, dc=userstore,dc=example,dc=com).

Apply the two LDIF files to the user data store schema.

For example, to update a DS instance, run the following command:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'id.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_add_kba_attempts.ldif \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_update_aci_kba_attempts.ldif
# Processing MODIFY request for cn=schema
# MODIFY operation successful for DN cn=schema
# Processing MODIFY request for dc=userstore,dc=example,dc=com
# MODIFY operation successful for DN dc=userstore,dc=example,dc=com

Upgrade from a version prior to 7.1 with a PingDS identity store

In the path where you deployed the openam.war file (for example, /path/to/tomcat/webapps/openam) locate the following file in the WEB-INF/template/ldif/opendj directory:

opendj_retry_limit_node_count.ldif

Update the identity store schema as follows:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'id.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_retry_limit_node_count.ldif

This schema update is required for the Save Retry Limit to User feature in the Retry Limit Decision node. The feature is enabled by default.

Even if you are not currently using the Retry Limit Decision node, you should make this schema update, in case you decide to use the node in the future. If you cannot update the identity store schema at this point, you must disable the feature.

Using push or web authentication, or using the ForgeRock SDK for device profiling

Apply the following LDIF files:

/path/to/openam/WEB-INF/template/ldif/opendj/push_2fa.ldif
/path/to/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif
/path/to/openam/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif

For example:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'id.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif\
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif

If you do not make this schema change, you must remove the webauthnDeviceProfilesContainer object class from the user configuration after the upgrade:

In the AM admin UI, go to Realms > Realm Name > Identity Stores > Identity Store Name.
On the User Configuration tab, remove webauthnDeviceProfilesContainer from the LDAP User Object Class.
Save your changes.

Make the same change for each identity store that does not have the schema change, and in each realm that uses the identity store.

Core Token Service (CTS) store

If you are updating from a version prior to AM 6.5, apply the following LDIF file to update the CTS schema:

cts-add-ttlexpire.ldif

If you are updating from a version prior to AM 6, also apply the following LDIF files:

cts-add-multivalue.ldif
cts-add-multivalue-indices.ldif

Replace the @DB_NAME@ variable inside the cts-add-multivalue-indices.ldif file with the CTS backend name. For example, replace occurrences of @DB_NAME@ with ctsStore.

Apply the schema updates:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'cts.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-multivalue.ldif \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-multivalue-indices.ldif \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-ttlexpire.ldif

After upgrade

Validate that the service is performing as expected.
Allow client application traffic to flow to the upgraded site.

Upgrade components and services

As part of planning your upgrade, consider that some changes in later AM versions will have an impact on your environment. Usually, these changes are driven by changes in specification, security policies, or performance.

When possible, the upgrade process makes the appropriate changes on AM configuration. However, sometimes you will need to perform additional configuration based on your environment needs.

In addition to the mandatory upgrade steps outlined in Upgrade AM instances, if you are using features described in these lists, you will need to perform further upgrade tasks.

Configure the user profile allowlist

AM 7 introduced a profile attribute allowlist.

The profile attribute allowlist controls the information returned to non-administrative users when they access json/user endpoints. For example, the allowlist controls the attributes shown in the user profile page.

Common profile attributes are allowlisted by default. You must add any custom attributes that you want non-administrative users to see.

The allowlist can be set globally, or per realm, in the user self-service service. To modify the list:

Globally: Go to Configure > Global Services > User Self-Service > Profile Management, and edit the Self readable attributes field.
By realm: Go to Realms > Realm Name > Services > User Self-Service > Profile Management, and edit the Self readable attributes field.

Note that you need to add the user self-service service to the realm if you have not done so already, but you do not need to configure anything other than the allowlist.

Note that the kbainfo attribute is required to be allow-listed for users to manage their KB questions and answers on user self-service flows.

Configure secret stores after upgrade

AM 6.5 introduced secret stores, which are repositories of cryptographic keys, key pairs, and credentials.

The upgrade process does not create all the demo key aliases created during a fresh install. This includes, for example, the aliases required for the IoT service. If you want to use services that require these demo aliases, add the corresponding keys and mappings after you have upgraded.
Although the configuration for secret stores is available to any upgraded server in the site, the upgrade process only creates the relevant secret store files on the AM instance where you run the upgrade process.

Follow these steps to make the secret stores available to other servers in the site:

Redeploy secret stores to a site after upgrade

You can reconfigure the secret stores and their mappings after upgrade. However, we recommend that you follow the steps in this procedure to ensure all secrets are available to all the instances in the site, and later on, you make additional changes to your environment.

The upgrade process creates several secret stores, globally and by realm, depending on the features configured in AM, and depending on the version you are upgrading from:

Go to Configuration > Secret Stores, and review the global secret stores created for your environment.
Reference: Global secret stores created after upgrade
Upgrade from AM 6 or earlier

default-keystore: a keystore-type secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process.

default-passwords-store: A filesystem secret store configured as the /path/to/openam/security/secrets/encrypted directory.

This directory contains the secrets to open the keystore configured in the default-keystore, and its keys.

UpgradeGlobalSecrets: A filesystem secret store configured as the /path/to/openam/security/secrets/encrypted/encrypted_hmac_key directory.

This directory contains the secrets used for the OAuth 2.0 server and the Persistent Cookie module.

Upgrade from AM 6.5 or earlier

default-keystore: a keystore-type secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process.

saml2-metadata-signing-keystore: A keystore secret store configured to the path of the AM keystore, as configured on the server where you ran the upgrade process.

default-encrypted_base64-store: A file system volume secret store that contains SAML v2.0 secrets that are base64-encrypted.

default-encrypted_plain-store: A file system volume secret store configured as the directory containing secrets related to the saml2-metadata-signing-keystore store.

The directory contains the password that was configured in the Metadata signing key password field of the global SAML v2.0 Service Configurations service.

It also contains the password files related to the default-keystore store if the default-passwords-store store does not exist.
- Ensure that the keystores configured exist on the other servers within the site. You may need to copy the keystores across or make them available in some other way.
- Ensure that directories configured in file system secret stores and their content exist on the other servers within the site. You may need to copy the directories across or make them available in some other way.
Go to Realms > Realm Name > Secret Stores, and perform the same actions you took for the global secret stores.

Reference: Realm-based secret stores created after upgrade

Realm-based secret stores are created for those features that supported different keystore configurations by realm; for example, SAML v2.0, or the persistent cookie module.

To find the realm-based secret stores, go to Realms > Realm Name > Secret Stores. The secrets themselves are stored in the /path/to/openam/security/secrets/realms/root/realm-name/secret-store-name directory.

If you have upgraded from a version which had SAML v2.0 Service Configurations at realm level, the upgrade process creates realm-level secret stores for the Metadata signing key alias field and its key, if they were configured.

Repeat this step for each of the realms you have configured.
Deploy the new AM .war file on the rest of the AM servers.
When the site is up, and before opening the service to end users, review the secret label mappings of the new secret stores and change them as required.

For example, the upgrade process may have created secret stores for features you aren’t using. These secret stores may have mappings to secrets that don’t exist. It’s advisable to remove unused secret mappings in production environments.

For details of the available secret labels, refer to Secret label default mappings.

Reference: SAML v2.0 mappings after upgrade

AM is flexible regarding the configuration of secrets for SAML v2.0. Therefore, migrating the different combinations may create a high number of secret labels in your environment.

As a rule of thumb, AM configures providers that were using the same key aliases in the same order, to use the same secret labels. If this rule can’t be satisfied, the upgrade process creates new secret labels for the provider by assigning it a secret label identifier.

If you have upgraded from a version which had SAML v2.0 Service Configurations, AM maps the am.services.saml2.metadata.signing.RSA secret label to the alias taken from the relevant Metadata signing key alias property of the service, either from the global service, or the realm-level services.

Upgrade device recovery codes

This section explains how to upgrade to AM 6.5 and later if you’re letting ForgeRock Authenticator users access and view device recovery codes.

AM versions earlier than 6.5 don’t encrypt the recovery codes stored alongside registered push and OATH devices. This allows the codes to be viewed by users at any time in their dashboard page. However storing credentials in plain text is considered a potential security risk, and from AM 6.5 onwards the recovery codes are displayed once, and then stored in a one-way encryption format, meaning they can never be viewed after their initial display.

After upgrading to AM 6.5 or later, when a user accesses their dashboard page, the stored recovery codes for each registered device will be one-way encrypted, meaning existing codes can no longer be displayed to the user.

This DOES NOT affect the ability to use the existing recovery codes, only the ability to display them in plain text to the user.

If you do not want to encrypt the recovery codes, and therefore retain the ability to show the codes to the user when requested, you can start AM with a Java property, as follows:

Prevent AM from encrypting device recovery codes

Perform these steps to prevent AM 6.5 and later from encrypting device recovery codes.

It is STRONGLY recommended that you encrypt recovery codes.

Locate or create the environment settings script for the container in which AM will run.

For example, the environment settings script for Apache Tomcat is located in /path/to/tomcat/bin/, and should be named setenv.bat (Windows) or setenv.sh (Unix).
In the relevant environment settings script, add the org.forgerock.openam.devices.recovery.use_insecure_storage=true property to the CATALINA_OPTS variable.

For example:
```
export CATALINA_OPTS="$CATALINA_OPTS -Dorg.forgerock.openam.devices.recovery.use_insecure_storage=true"
```
For containers other than Apache Tomcat, perform an analogous step to add the Java option to the scripts used to startup the AM instance.
Start the container in the usual manner.

For example, ./startup.sh.

AM will not encrypt device recovery codes when created, or when first accessed. When preventing AM from encrypting the stored recovery codes, be aware of the following points:
- Users will only see registered devices on their dashboard that are of the same type that they have used to authenticate.
  
  For example, if they authenticated using a registered OATH device, they will not see any registered push or WebAuthn devices on their dashboard. This is to prevent users being able to see recovery codes for devices that they did not authenticate with.
- The option to view the recovery codes for a device has been removed from the user interface.
  
  However, the recovery codes are returned in the JSON response when querying the /devices/2fa/ endpoint. You will need to provide a customized user interface to display these codes.
- If the container in which AM is running is ever started without the org.forgerock.openam.devices.recovery.use_insecure_storage=true property, a query to any of the /devices/2fa/ endpoints will cause AM to one-way encrypt the recovery codes.

Upgrade JDBC audit event handlers

If you had configured one or more JDBC audit event handlers, make the following changes to the audit tables' schema:

Run the following command on Oracle databases that support AM audit event handlers:
```
ALTER TABLE am_auditaccess ADD (response_detail CLOB NULL);
```
This command adds the response_detail column to the am_auditaccess table.
Run the following commands on MySQL databases that support AM audit event handlers:
```
ALTER TABLE audit.am_auditconfig CHANGE COLUMN configobjectid objectid VARCHAR(255);
ALTER TABLE audit.am_auditaccess ADD COLUMN response_detail TEXT NULL;
```
The commands change the name of the configobjectid column in the am_auditconfig table to objectid and add the response_detail column to the am_auditaccess table.
If you use databases other than Oracle or MySQL to support AM audit event handlers, review their schema.

If the am_auditconfig table has a column named configobjectid, change that column’s name to objectid.

If the am_auditaccess table does not have a column named response_detail, add that column to the table’s schema.

Migrate legacy instances

Rather than upgrade legacy instances (running an OpenAM or AM version that is no longer supported), you must instead manually migrate from your existing deployment to a new deployment.

For complex legacy deployments, Ping Identity can help you with the migration process.

Upgrade a legacy deployment

Prepare your customized AM WAR file.
Prepare a new deployment, installing servers from the new, customized WAR file, starting with the instructions in Install AM.
After installation, configure the new servers in the same way as the old servers, adapting as necessary.
Validate that the new service is performing as expected.
Redirect client application traffic from the old deployment to the new deployment.

Migrate to a file-based configuration

AM stores different types of information. For the purposes of this topic, we distinguish between the following types:

Configuration: Relatively static information that doesn’t change frequently after initial setup. Only administrative users can change it.
Data: Information that changes at runtime, often due to end user action. Examples of data are identities, CTS tokens, policies, agents, and applications.

Currently, AM stores configuration and data in LDAP directories.

In a future release, AM will read its configuration only from JSON files, not directory servers. Using LDAP data stores for configuration will be deprecated and file-based configuration (FBC) will be the only supported configuration storage mechanism. Dynamic data will continue to be stored in LDAP directories.

To prepare to migrate your configuration from LDAP directories to JSON files, AM 7.4 provides a technology preview of a configuration migration utility based on the existing amupgrade command. The purpose of this technology preview is to let you test migrating custom configuration to FBC.

When you test the migration utility, focus on schema that you have customized or modified, to identify combinations of attributes that the utility doesn’t yet consider. In such cases, the migration utility shouldn’t fail, but will produce output highlighting any errors it encountered.

Although this feature isn’t yet supported in production, we’d appreciate you reporting these errors by submitting feedback on this topic. Click the feedback icons at the top of this page.

Any reports you submit will be taken into account to ensure you can migrate seamlessly when FBC becomes the mandatory configuration storage mechanism.

The interface stability for the file-based configuration (FBC) migration utility is Technology Preview. Technology previews offer access to new technology not yet supported. Technology preview features may be functionally incomplete and subject to change without notice. For details, refer to Interface stability.

The purpose of this technology preview is to allow you to test the migration of your configuration data. The technology preview should function correctly but may highlight areas that need improvement before the supported release of this feature.

AM configuration stored in PingDS remains supported as documented in this release. In a future AM release, LDAP configuration stores will be deprecated in favor of FBC.

Before you start

Before you migrate your configuration to FBC, read the following:

Supported migration paths
Identify where your configuration is stored
Export existing configuration data
Structure the output

Do not run the migration utility in a production environment. Use a development or test environment.
The migration utility assumes an external LDAP configuration store. The embedded DS datastore isn’t supported in production deployments. From AM 8.0.0 onwards, the embedded DS datastore will be removed entirely.

Supported migration paths

You can use this migration utility only to migrate configuration data from AM versions 7.1.x, 7.2.x, and 7.3.x. You can only use the generated file-based configuration with AM version 7.4.0.

To migrate configuration data from earlier versions, first upgrade the configuration to AM version 7.1, 7.2, or 7.3, and then run the migration utility to get the FBC.

Identify where your configuration is stored

The migration utility creates files that replace the configuration stored in LDAP directories. Most deployments have one or more external LDAP directories to store configuration and data (identities, CTS tokens, policies, agents, and applications).

An LDAP directory that stores configuration and data will still contain the configuration after migration, but AM won’t use that configuration. The migration utility output helps you clean up the datastore to remove redundant configuration after migration.

Identify the datastore that contains your configuration. If you use the default options to install DS for AM configuration, the configuration is stored under ou=services,ou=am-config. Everything else under ou=am-config is regarded as runtime data rather than configuration.

The migration utility doesn’t migrate this data to FBC. It does, however, write the data out to a separate LDIF file, nonmigrated-entries.ldif. You can import this data from the LDIF file to a standalone LDAP server.

Export existing configuration data

The migration tool consumes an LDIF export of the existing configuration.

If the configuration store is PingDS, you can use the export-ldif command to export the data, supplying the following parameters:

The backend ID of the configuration store, cfgStore by default.
The base DN of the branch containing the configuration, ou=am-config by default.
An LDIF filename in which to store the exported configuration.

The following example, run on the DS server, assumes the default parameters when DS is installed for AM configuration:

$ /path/to/opendj/bin/export-ldif \
--backendId cfgStore \
--includeBranch ou=am-config \
--ldifFile /path/to/export-config/exported-configuration.ldif \
--offline
…
 category=BACKEND severity=INFO seq=36 msg=Exported 1480 entries and skipped 0 in 0 seconds (average rate 5522.4/sec)

The exported file contains the existing configuration under ou=am-config:

$ more /path/to/export-config/exported-configuration.ldif
dn: ou=am-config
objectClass: top
objectClass: untypedObject
ou: am-config
…

Structure the output

By default, the configuration is exported to JSON files as a flat list of properties. For some services, the AM admin UI structures the configuration in logical groups. You can mimic this structure in the migrated JSON files by pointing the migration utility to a target AM .war file, resulting in FBC that’s easier to read.

Before you run the migration utility, ready the target AM .war file so that you can generate this structured output.

Migrate your configuration

The migration utility is an enhanced version of the AM configuration upgrader available in AM-7.5.1.zip.

If you don’t already have it, download the AM ZIP file from the BackStage download site.
Extract the contents of the ZIP file.
In the extracted openam directory, locate and extract the Config-Upgrader-7.5.zip file.

To migrate the LDAP configuration, run the amupgrade command with the migrationMode argument. Refer to the Migration command-line arguments for details of each argument:

$ /path/to/amupgrade \
--migrationMode \
--inputConfig input-directory \
--output output-directory \
--sectionsSource target-war-file \
rules-file-path

Migration command-line arguments

Because migration mode isn’t yet supported in production deployments, some of these arguments aren’t exposed in the --help command.

-i | --inputConfig: The directory containing the LDIF configuration files that you’re migrating.
-o | --output directory: The directory to which the migration utility writes the generated FBC.
-M | --migrationMode: Runs the upgrade command in migration mode (required if you’re testing migration to FBC).

Default: false.

-s | --sectionsSource (optional)

A file that specifies the structure (section details) of the output configuration.

Without this option, the migration utility generates the configuration properties as flat files.

This file can be a section.properties file for a specific service or an AM.war file that includes the structure for all services.

Example section.properties file for JSON audit handler

########################################################################################################################
# Common handler section properties
########################################################################################################################
commonHandler=enabled
commonHandler=topics

########################################################################################################################
# Common handler plugin section properties
########################################################################################################################
commonHandlerPlugin=handlerFactory

########################################################################################################################
# JSON handler section properties
########################################################################################################################
jsonConfig=location
jsonConfig=elasticsearchCompatible
jsonConfig=rotationRetentionCheckInterval
jsonFileRotation=rotationEnabled
jsonFileRotation=rotationMaxFileSize
jsonFileRotation=rotationFilePrefix
jsonFileRotation=rotationFileSuffix
jsonFileRotation=rotationInterval
jsonFileRotation=rotationTimes
jsonFileRetention=retentionMaxNumberOfHistoryFiles
jsonFileRetention=retentionMaxDiskSpaceToUse
jsonFileRetention=retentionMinFreeSpaceRequired
jsonBuffering=bufferingMaxSize
jsonBuffering=bufferingWriteInterval

rules-file-path

The path to the upgrade rules file.

Although you’re not using this command to upgrade to a new version, the amupgrade command requires an upgrade rules file.

Use the noop.groovy file (located in (/path/to/amupgrade/rules/fbc/noop.groovy) to migrate the configuration without applying any rules.

Example

$ /path/to/amupgrade \
--migrationMode \
--inputConfig /path/to/export-config \
--output /path/to/am/config/services \
--sectionsSource /path/to/AM-7.5.0.war \
/path/to/amupgrade/rules/fbc/noop.groovy

In the preceding example, the new JSON configuration files are generated in /path/to/am/config/services. By default, AM reads FBC from the $AM_HOME/config/services directory, so use this as the output directory.

After the migration, the output directory contains JSON representations of the global and realm configuration services and a nonmigrated-entries.ldif file with data that wasn’t migrated to JSON.

For example, the configuration of the alpha realm is as follows:

$ more /path/to/am/config/services/global/realms/root-alpha.json
{
  "metadata": {
    "realm": "/alpha",
    "entityType": "",
    "entityId": "L2FscGhh",
    "uid": "o=alpha,ou=services,ou=am-config",
    "sunServiceID": null,
    "objectClass": [
      "sunRealmService",
      "top"
    ],
    "pathParams": {},
    "ou": []
  },
  "data": {
    "_id": "root-alpha",
    "_type": {
      "_id": "",
      "name": "",
      "collection": false
    },
    "active": true,
    "aliases": [
      "alpha"
    ],
    "parentPath": "/",
    "name": "alpha"
  }
}

Configure AM for FBC

When you’ve migrated your configuration to JSON files, you can point your AM instances to the FBC.

If your policy and application data is still in the original LDAP data store, you’ll need to continue using that datastore for the runtime data. Eventually, you should move the runtime data to its own datastore, and retire the original directory server, or remove the redundant configuration from the original datastore.

These instructions assume a local AM server running in an Apache Tomcat container. Adjust the instructions to suit your environment.

Configure AM for file-based mode:
1. Stop AM or the container in which it runs.
2. Set the following Java variables to true:
  
  com.sun.identity.sm.sms_object_filebased_enabled=true com.sun.identity.sm.filebased_embedded_enabled=true
3. Pass those variables to AM in some way. For example, for Tomcat you can set them in the CATALINA_OPTS options:
  
  export CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.identity.sm.sms_object_filebased_enabled=true -Dcom.sun.identity.sm.filebased_embedded_enabled=true"
Provide the configuration files to AM.

AM reads FBC from its home directory. You’ll need access to this directory on your local host or in your Docker container.

For local hosts, change to the $AM_HOME/config/services directory:
```
$ cd $AM_HOME/config/services
```
Copy the migrated configuration into the services directory.
```
$ cp /path/to/new-config $AM_HOME/config/services
```
If the directory contains default configuration, delete it before copying in your migrated configuration.
Restart AM or the container in which it runs.
Start up and test your environment.

Check that AM has the configuration you expect. You can also make changes to your configuration through the AM admin UI and check that those changes are made in the JSON configuration files.

Report any problems you encounter during the migration process, including significant performance issues.

If you use an external policy and application store, you must restart AM with the com.sun.identity.sm.filebased_embedded_enabled Java variable turned off after you’ve set up the policy and application store.

Stop AM or the container in which it runs.
Set com.sun.identity.sm.filebased_embedded_enabled to false or simply remove it from the variables passed to AM. For example:

export CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.identity.sm.sms_object_filebased_enabled=true"

PingAM 7.5.1

Upgrade

Before you upgrade

Upgrading servers

Upgrading components

Name changes for ForgeRock products

Supported upgrade paths

Plan the upgrade

Route around servers during downtime

Back up the deployment

Review REST API versions before upgrading

Review PingDS certificates before upgrading

Customize before upgrading

Plan for rollback

Upgrade in a test environment first

Upgrade AM instances

Before you upgrade

Upgrade the server and configuration

amupgrade

Upgrade paths with amupgrade

Before you start

Upgrade from an Amster configuration export

Upgrade wizard

openam-upgrade-tool

Update tools, scripts, and components

Update the schema

Configuration store

Identity store

Core Token Service (CTS) store

After upgrade

Upgrade components and services

Configure the user profile allowlist

Configure secret stores after upgrade

Redeploy secret stores to a site after upgrade

Upgrade device recovery codes

Prevent AM from encrypting device recovery codes

Upgrade JDBC audit event handlers

Migrate legacy instances

Upgrade a legacy deployment

Migrate to a file-based configuration

Before you start

Supported migration paths

Identify where your configuration is stored

Export existing configuration data

Structure the output

Migrate your configuration

Configure AM for FBC

`amupgrade`

Upgrade paths with `amupgrade`

Upgrade from an `Amster` configuration export

`openam-upgrade-tool`