Upgrading AM Instances
Upgrading AM is a process that consists of 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 navigate 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-18.104.22.168.jar, which you install as described in "To Set Up the Configuration Tools".
Perform the steps in the following procedure to upgrade AM:
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 7 and will be removed in a future release.
(AM 6 or earlier) Go to Deployment > Servers > Server Name > Advanced, and check the value of the
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
opendsdirectory exists under the
You may have migrated it to an external directory and not deleted the directory, though. Check the files in the
opends/logsdirectory 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:
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/OpenDJ in AM/OpenAM (All versions)? in the ForgeRock Knowledge Base.
Add a new external DS instance and replicate data from the embedded instance.
Follow the steps in Add a New Replica Before Upgrade in the DS Upgrade Guide.
Ensure you have read Planning the Upgrade and planned your upgrade accordingly.
Prepare your customized AM server
.warfile. For more information, see "Customizing Before Upgrading".
Back up your deployment. For more information, see "Backing Up the Deployment".
Route client application traffic to another site during the upgrade. For more information, see "Routing Around Servers During Downtime".
Ensure that an AES 256-bit key called
directenctestis 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.
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
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.
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
(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
When you deploy the new
.warfile, 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/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.ldifschema to your external user data store when you configured it.
For more information about LDIFs, see "Supported LDIF Files".
To update the user store schema, perform the following steps:
Change directories to the path where you have deployed the
openam.warfile. For example,
Locate the following files in the
If your user data store is not DS, use these files as examples to create files suitable for your environment.
opendj_update_aci_kba_attempts.ldiffile and replace
@SM_CONFIG_ROOT_SUFFIXwith the base DN defined during the DS installation procedure (for example,
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.warfile. For example,
opendj_retry_limit_node_count.ldiffile in the
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:
Navigate 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
These files are used only by the install and upgrade wizards. Removing them will have no effect on your installed instance.
openam-upgrade-tool-22.214.171.124.jartool for an unattended upgrade:
openam-upgrade-tool-126.96.36.199.jartool as described in "To Set Up the Configuration Tools". A
sampleupgradefile will be expanded in the directory where you install the tool.
Create a configuration file for the
openam-upgrade-tool-188.8.131.52.jar. You can use the
sampleupgradefile as a template to create a configuration file, for example
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-184.108.40.206.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, see 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.1135220.127.116.113")(version 3.0; acl "Allow server-side sorting"; allow (read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)
See "Preparing Configuration Stores" for more information about configuring AM configuration stores.
Update the identity store schema as follows:
Log into AM.
Navigate to Realm Name > Datastores > External User Store.
Click Load Schema before saving, and then 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, see "Updating 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:
If you are updating from a version prior to AM 6, also apply the following LDIF files:
@DB_NAME@variable inside the
cts-add-multivalue-indices.ldiffile with the CTS backend name. For example, replace occurrences of
/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
(Optional) 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/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
webauthnDeviceProfilesContainerobject class from the user configuration after upgrading AM.
In the AM console, go to Realms > Realm Name > Identity Stores > Identity Store Name. On the User Configuration tab, remove
webauthnDeviceProfilesContainerfrom the LDAP User Object Class property, and then 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 "Supported LDIF Files".
Once the new tools are working, delete the old tools.
Review the information in Upgrading Components and Services and decide if you need to reconfigure any of AM's services or features.
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:
Read the release notes for information about possible changes.
Install an AM 7.1.3 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.