Upgrade AM instances

To upgrade an AM deployment, you must upgrade each server instance in your site. For older AM versions, you might not be able to upgrade directly to AM 7.3. For details, refer to 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.

Configuration

Use one of the following methods to upgrade the configuration:

amupgrade

This utility is provided in the AM-7.3.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.21.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 ForgeRock Directory Services (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 ForgeRock 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 ID.
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 configure a different key in the secret ID mapping. Make sure the secret ID is always mapped to an existing, resolvable secret or key alias.

Upgrade the configuration

Use one of the following methods to upgrade the 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.1.x	7.2.x, 7.3.x
7.2.x	7.3.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.1.x

7.2.x, 7.3.x

7.2.x

7.3.x

You cannot use amupgrade to upgrade a running AM instance.

Before you start

Download the AM ZIP file from the ForgeRock BackStage download site.
Extract the contents of the ZIP file.
In the extracted openam directory, locate the Config-Upgrader-7.3.1.zip file.
Extract the Config-Upgrader 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 in which the updated configuration should be saved
- amster version is the version of Amster you’ll 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/AM7Config/ \ -o /path/to/AM7.3Config \ -a 7.2 \ rules/amster/7.2.x-to-7.3.x.groovy Reading existing configuration from files in /path/to/AM72-config/… Modifying configuration based on rules in [rules/amster/7.2.x-to-7.3.x.groovy]… reading configuration from Amster json files Writing configuration to new location at /path/to/AM7.3Config… Upgrade Completed, modified configuration saved to /path/to/AM7.3Config
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.
Follow the Amster documentation to import the upgraded configuration.

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 reference to click-servlet from the deployment descriptor file. Edit /path/to/openam/WEB-INF/web.xml to remove the following mapping:
<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.

Set up the configuration tools to install the openam-upgrade-tool-14.1.3.21.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.21.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.21.jar, refer to the reference documentation.

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.
Ensure that the AM scripts are current, and that they contain the modifications that 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.3.1 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 ForgeRock Directory Services, 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 \
--trustStorePasswordFile /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 ForgeRock Directory Services 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 \
--trustStorePasswordFile /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 \
--trustStorePasswordFile /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 \
--trustStorePasswordFile /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.