Upgrade AM instances

Upgrading AM involves upgrading the AM instance or instances in your site and, depending on the version you are upgrading from, updating the configuration of several AM features.

When possible, the upgrade process makes the appropriate changes on AM configuration on your behalf. However, sometimes you will need to perform additional configuration based on your environment needs. It is imperative that you read the Release Notes and understand the changes introduced in each version before upgrading AM.

Upgrade AM using the Upgrade wizard, which appears when you replace a deployed AM .war file with a newer version and go to the deployment URL. The Upgrade wizard brings the AM configuration, including the version number, up to date with the new version.

The CLI counterpart of the Upgrade wizard is openam-upgrade-tool-14.1.3.18.jar, which is installed when you set up the configuration tools.

Perform the steps in the following procedure to upgrade AM:

Upgrade from a supported version

Follow these steps to upgrade a site of instances. For information on the versions that are supported for upgrade, see Supported upgrade paths.

Do not perform an upgrade by deploying the new version and then importing an existing configuration by running the ssoadm import-svc-config command.
The embedded DS server is not supported for production in AM 7. If you have an existing site configured with embedded DS, you must migrate it to an external DS store before upgrading to AM 7.

The embedded DS is 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 one of the following methods to migrate an embedded data store to an external store before attempting to upgrade AM:
- 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 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 start, make sure that you have planned your upgrade.
Prepare your customized AM server .war file.

For more information, see Customize before upgrading.
Back up your deployment.

For more information, see Back up the deployment.
Route client application traffic to another site during the upgrade.

For more information, see Route around servers during downtime.
Ensure that an AES 256-bit key called directenctest is available to all the instances in the site.

It does not need to be the same key that AM provides on the default keystore.

Failure to provide this key will prevent AM from starting up after upgrade.

What is this key for?

AM uses this key to encrypt information stored in the secure state of the authentication trees, which is a new and mandatory feature of the trees in AM 7 and later.

The upgrade process will map this key to the am.authn.trees.transientstate.encryption secret ID.

The way you make the alias available depends on the version of AM you are upgrading from:
- Versions 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.
- AM 6.5
  
  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 provide this secret, or you can add it to one of your existing stores.
  
  The following is an example of how to create 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.
  Make sure that the alias is available to all instances of the site. This may mean, for example, copying the keystore across the site.
  
  After the upgrade, you can rename the key alias or configure a different key in the secret ID mapping, but ensure that this secret ID is always mapped to an existing, resolvable secret or key alias.
Stop AM or the container where it runs.
Deploy your customized server .war file.

When you deploy the new .war file, you might have to delete working files left by the old installation. For example, if you deploy on Apache Tomcat, replacing /path/to/tomcat/webapps/openam.war, then also 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.
You must update the identity store XML schema if you are upgrading from a version of AM earlier than 6 and any of the following statements are true:
- You have configured knowledge-based (KBA) user self-service questions.
- You have not configured User Self-Service yet, but you added the user_store_type_kba.ldif schema to your external user data store when you configured it.
  
  For more information about LDIFs, see Set up directory schemas with LDIF.
  
  To update the user store schema, perform the following steps:
- Change directories to the path where you have deployed the openam.war file.
  
  For example, /path/to/tomcat/webapps/openam .
- Locate the following files in the WEB-INF/template/ldif/opendj path:
  - opendj_add_kba_attempts.ldif
  - opendj_update_aci_kba_attempts.ldif
  If your user data store is not DS, use these files as examples to create files suitable for your environment.
- Open the opendj_update_aci_kba_attempts.ldif file and replace @SM_CONFIG_ROOT_SUFFIX with the base DN defined during the DS installation procedure (for example, dc=userstore,dc=example,dc=com).
- Update the user data store schema with the two files.
  
  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
Note that you will need to update the user store schema again in a later step, whether you performed this step or not.

(DS identity stores only) Update the identity store XML schema if you are upgrading from a version of AM earlier than 7.1.

This step is required to use the Save Retry Limit to User feature in the Retry Limit Decision node, which is enabled by default.

Even if you are not using the node now, ForgeRock recommends that you update the schema should you decide to use it in the future. If you cannot update the identity store schema at this point, you must disable the feature.

To update the identity store schema, perform the following steps:

Change directories to the path where you have deployed the openam.war file. For example, /path/to/tomcat/webapps/openam.
Locate the opendj_retry_limit_node_count.ldif file in the WEB-INF/template/ldif/opendj path.

You will apply more changes to the user schema in a later step. That step will also update your identity user store for this feature if you are not using DS.

Update the identity store schema.

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

To upgrade the data in the configuration store, perform one of the following actions in one of the servers in the site:

Go to the AM URL, for example https://openam.example.com:8443/openam, and follow the instructions in the Upgrade Wizard for an interactive upgrade.

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. When complete, AM prevents access to the upgrader UI itself.
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>

Use the openam-upgrade-tool-14.1.3.18.jar tool for an unattended upgrade:

Install the openam-upgrade-tool-14.1.3.18.jar tool as described in To Set Up the Configuration Tools.

A sampleupgrade file will be expanded in the directory where you install the tool.
Create a configuration file for the openam-upgrade-tool-14.1.3.18.jar.

You can use the sampleupgrade file as a template to create a configuration file, for example upgrade.properties.

An upgrade configuration file may resemble the following:
```
$ grep -v "^#" upgrade.properties
SERVER_URL=http://openam.example.com:8080
DEPLOYMENT_URI=/openam
ACCEPT_LICENSES=true
```

Upgrade AM by using the tool with the properties file following this example:

$ java -jar openam-upgrade-tool-14.1.3.18.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 additional information about the command-line tool, refer to the reference documentation for upgrade.jar.

Restart AM or the container where it runs.

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.
Update the identity store schema as follows:
- Log into AM.
- Go to Realms > Realm Name > Datastores > External User Store.
- Click Load Schema before saving, and click Save to apply your changes.
- If you have additional user stores, repeat the previous steps for each user store.
If you need to manually update your identity store user schema, refer to Update the schema in an external identity repository.

Depending on the version from which you are upgrading, you might need to update the schema in the Core Token Service (CTS).

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

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.

For example:

$ /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

If you intend to use push or web authentication, or to use the ForgeRock SDK for device profiling, then you must update your identity store user schema. You can ensure the correct parameters are available by applying 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 apply these schema changes, remove the webauthnDeviceProfilesContainer object class from the user configuration after upgrading AM .

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 property, and save your changes.

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

For more information on these LDIF files, and the equivalent files for supported directory servers, see Set up directory schemas with LDIF.

Install a new version of the AM tools as described in Set up administration tools and in the ForgeRock Identity Platform Amster User Guide.

Once the new tools are working, delete the old tools.

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.

Ensure that the AM scripts are current, and that they contain the modifications that your environment requires.

To avoid overwriting changes done to the original files, the upgrade process does not update scripts from earlier versions of AM. Ensure that the scripts in your environment are compatible with the version of AM you upgraded to by performing the following steps:
1. Read the release notes for information about possible changes.
2. Install an AM 7.2 test environment, and compare the scripts.
  
  New installations always have the current scripts.
Validate that the service is performing as expected.
Allow client application traffic to flow to the upgraded site.

AM 7.2.2

Upgrade AM instances

Upgrade from a supported version