Access Management 7.3.2

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 ForgeRock 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.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Supported upgrade paths

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

Upgrade paths
Version Upgrade Supported?

AM 6.5.x

✔

AM 7.x

✔

For details, refer to the Ping Identity Product Support Lifecycle Policy in the Knowledge Base.

If you are upgrading from an unsupported version 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.

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

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.3.2:

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, identifying 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

Upgrading servers takes at least one of your AM sites down while the server configurations are being brought up to date with the newer version. Plan for this site to be down, routing 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 you must restrict access to the AM console: The Upgrade Wizard page does not require authorization; any user with access to the AM admin UI immediately after you deploy the new WAR file can therefore initiate the upgrade process.

Back up the deployment

Always back up your deployment before you upgrade, as you must be able to roll back should something go wrong during the upgrade process.

  • Backing up your configuration as described in Back up configurations is good for production environments.

  • 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 tools scripts that you have edited for your deployment. Also back up any trust stores used 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 will need to be added again 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 do not specify API version information in REST calls.

By default, an upgraded AM instance responds to REST calls that do not 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 more information, see Specifying REST API Versions.

Starting in version 6, AM includes a CSRF protection filter that is enabled by default. REST requests other than GET, HEAD, and OPTIONS made to endpoints under the json/ root will return 403 Forbidden messages unless one of the X-Requested-With or Accept-API-Version headers are added to it.

For more information, see Protect against CSRF attacks.

You can configure AM’s default REST API behavior. For more information, see Configuring the Default REST API Version.

Review Directory Services certificates before upgrading

Before upgrading, review that 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 does not match the FQDN obtained from DNS for the DS instance, AM will not be able to establish a secure connection with DS. Additionally, if the DS instance responds to multiple FQDNs, they must be specified in the certificate as well.

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, see 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 oftentimes changes the samples provided with AM.

    Do not copy custom plugins or extensions from a previous version of AM to the .war file.

    You must customize the samples of the version you are upgrading to before adding them to the .war file. For example, download the custom scope validator sample of the version you are 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 to go smoothly. In such cases, you need a plan to roll back smoothly 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 restarting the old servers. For more information, see Back up configurations.

Upgrade in a test environment first

Always try upgrading AM in a test environment before applying the upgrade in your production environment.

This will help you gauge the amount of work required without affecting your production environment, and will help smooth out 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:

  1. 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.

  2. 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.3. 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.3.2.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 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:

Before you upgrade

You must follow these steps before you start an upgrade.

  1. Plan your upgrade.

  2. Prepare a customized AM .war file.

  3. Back up your deployment.

  4. Route client application traffic to another site during the upgrade.

  5. 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 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.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

  1. Download the AM .zip file from the ForgeRock BackStage download site.

  2. Extract the contents of the .zip file.

  3. In the extracted openam directory, locate the Config-Upgrader-7.3.2.zip file.

  4. Extract the Config-Upgrader-7.3.2.zip file.

Upgrade from an Amster configuration export

  1. Follow the Amster documentation to export your configuration.

  2. 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.

  3. 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.

  4. Stop AM or the container where it runs.

  5. 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/

  6. Install the new version of AM using the new DS server for your configuration store.

  7. Follow the Amster documentation to import the upgraded configuration.

  8. 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.

  1. Stop AM or the container where it runs.

  2. 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.

  3. Restart AM or the container where it runs.

  4. 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.

  5. Go to the deployment URL and follow the prompts to upgrade.

  6. Restart AM or the container where it runs.

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

  1. Stop AM or the container where it runs.

  2. 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.

  3. Restart AM or the container where it runs.

  4. 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.

  5. 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

  6. 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.

  7. Restart AM or the container where it runs.

Update tools, scripts, and components

  1. 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.

  2. 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.3.2 test environment, and compare the scripts.

      New installations always have the current scripts.

  3. 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.

  1. 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.

  2. 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).

  3. 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

  1. 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

  2. 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:

  1. In the AM admin UI, go to Realms > Realm Name > Identity Stores > Identity Store Name.

  2. On the User Configuration tab, remove webauthnDeviceProfilesContainer from the LDAP User Object Class.

  3. 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

  1. Validate that the service is performing as expected.

  2. 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 additional upgrade tasks:

Changes in AM 7.2
Changes to the OIDC claim classes

  • The org.forgerock.openidconnect.Claim class has been deprecated. The new org.forgerock.oauth.clients.oidc.Claim class, in the ForgeRock commons library, replaces its functionality.

    This new class has a getNameWithLocale() method that returns a string of claim names, appended with # and the locale, in line with the OIDC specification.

    A new getJavaLocale() method has been added to the Claim class, and lets a caller get the Locale object associated with the claim. The existing getLocale() method remains unchanged, and is equivalent to calling getJavaLocale().toLanguageTag().

  • The new Claim class contains a ClaimBuilder class, that you should use to create instances of the Claim. The Claim class is immutable and should not be extended. (It cannot be marked as final, for compatibility reasons.)

  • The ClaimBuilder class no longer contains a withValues method. This method has been split into the following, more granular methods (with corresponding new methods for single items):

    • withBooleanValues and withBooleanValue

    • withNumericalValues and withNumericalValue

    • withJsonValues and withJsonValue

    • withStringValues and withStringValue

  • The new ClaimsMapper class separates and encapsulates the functionality for converting claims to and from JSON. The `asMap method has therefore been removed from the Claim class.

Anonymous user inactive by default

The default anonymous user, used, for example, by the Anonymous User Mapping node, is now Inactive by default. If you have existing nodes, modules, or other clients that reference this user, you must explicitly set the user status to Active.

normalized-profile-to-managed-user scripts

For Apple SSO configurations that use the Request Native App for UserInfo property, the normalized-profile-to-managed-user.groovy and normalized-profile-to-managed-user.js scripts have been updated to set a flag that specifies how userinfo objects should be patched.

If you use these scripts, or a custom variation of these scripts, in your Apple SSO authentication tree, you should update your scripts to set the flag. You should also update your social provider journey to add a Scripted Decision node, as described in Request Native App for UserInfo.

Connections made by the CTS

OPENAM-13855 corrected an issue where the CTS was creating too many connections to the Directory Services. This fix might imply that the number of connections created is now different in your deployment, corrected to be the expected number of connections. Monitor your environments to ensure that this corrected number of connections is sufficient, and increase it if necessary.

Script content stored in clear text

In file-based configurations, script content is now stored in cleartext, rather than as a base64-encoded string. This makes it easier to find differences between old and new configurations. If you are upgrading AM from a previous version, existing scripts will still appear as base64-encoded strings in their corresponding configuration files. These scripts must be saved again in order for the cleartext script content to be stored in the configuration file. Note that script content is still base64-encoded in REST requests and responses.

OAuth 2.0 token introspection

  • The /oauth2/introspect endpoint now returns an additional member, username, which specifies the user that authorized the introspected token.

    As part of this change, the user_id member, which was used by earlier versions of the specification, is deprecated. It will be removed in a future version of AM.

    This change aligns the endpoint’s response with the OAuth 2.0 Token Introspection specification.

  • HTTP GET requests are now disallowed on the /oauth2/introspect endpoint by default. Using token as a query parameter on this endpoint is also disallowed. To change this behavior to suit existing clients, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

  • AM 7.2 changes the way the /oauth2/introspect and the /oauth2/tokeninfo endpoints return the value of the expires_in object.

    The expires_in object specifies the time, in seconds, that a token is valid for. For example, 3600 seconds. This value is set at token creation time, and it depends on the configuration of the OAuth2 Provider Service.

    When providing a token introspection or token information response, earlier versions of AM returned the value of the expires_in object as it was stored in the token. This means that any call to the endpoints while the token is valid returned the same value for the expires_in object.

    AM 7.2 calculates the amount of seconds the token is still valid for and returns this value in the expires_in object. Therefore, repeated calls to the endpoints return different values for the object.

    However, the actual value of the expires_in object in the token does not change. Inspecting the token without using AM will show the value set at token creation time.

    The expires_in object is not always present in the endpoint response:

    • Introspection endpoint: AM only returns the expires_in object for client-side tokens issued to a client configured in the same realm as the resource owner’s.

    • Token information endpoint: AM does not return the expires_in object for client-side tokens issued to a client configured in a different realm than the resource owner’s.
OpenID Connect userinfo endpoint

AM 7.2 changes when the aud and iss objects are returned in the JWT response of the /oauth2/userinfo endpoint.

Earlier versions of AM returned the iss object when the user information response was a signed, encrypted, or a signed and encrypted JWT. The aud object was never returned.

AM 7.2 now returns both the aud and iss objects when response is a signed, or a signed and encrypted JWT, according to the OpenID Connect Core 1.0 incorporating errata set 1 specification.

The iss object is no longer returned when the response is an encrypted JWT.

Web and Java agent properties in AM admin UI

  • Web agent properties added

    • Use Built-in Apache HTTPD Authentication Directives (com.forgerock.agents.no.remoteuser.module.compatibility)

    • Hostname to IP Address Map (com.forgerock.agents.config.hostmap)

    • Retain Session Cache After Configuration Change (com.forgerock.agents.session.cache.eventually.consistent)

  • Java agent properties added

    • Recheck availability of AM (org.forgerock.agents.am.unavailability.recheck.window.in.seconds)

    • Enable Notification of Session Logout (org.forgerock.agents.session.change.notifications.enabled)

  • Deprecated Java agent properties removed

    • Fall-Forward Mode (org.forgerock.agents.fallforward.mode.enabled)

    • PDP Cache TTL in Milliseconds (com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl)

  • Java agent property name changes

    The Java Agent property names have changed in AM admin UI. The new names reflect the names now used in the Java Agent documentation.

    Summary of new names
    Old Name New Name

    Accept SSO Tokens

    Enable SSO Token Acceptance

    Agent Configuration Change Notification

    Enable Notifications of Agent Configuration Change

    Agent Filter Mode

    Agent Filter Mode Map

    Allow Custom Login Mode

    Enable Custom Login Mode

    AM Conditional Login URL

    OAuth Login URL List

    AM Conditional Logout URL

    Conditional Logout URL List

    AM Login URL

    AM Login URL List

    Application Logout URI

    Logout URI Map

    Attribute Cookie Encode

    Enable Attribute Encoding

    Authentication Fail Reason Url

    Authentication Fail URL

    CDSSO Domain List

    JWT Cookie Domain List

    CDSSO Redirect URI

    Authentication Redirect URI

    Continuous Security Cookies

    Continuous Security Cookie Map

    Continuous Security Headers

    Continuous Security Header Map

    Convert SSO Tokens into OpenID Connect JWTs

    Convert SSO Tokens Into OIDC JWTs

    Cookies Reset Domain Map

    Reset Cookie Domain Map

    Cookies Reset Name List

    Reset Cookie List

    Cookies Reset Path Map

    Reset Cookie Path Map

    Custom Conditional Login URL

    Legacy Login URL List

    Custom Response Header

    Custom Response Header Map

    Encode Cookies

    Enable Encoded Cookies

    Exchanged SSO Token Cache Size

    Max Entries in SSO Exchange Cache

    Exchanged SSO Token Cache Time to Live

    Exchanged SSO Token Cache TTL

    Expired Session Cache Max Records

    Max Entries in Expired Session Cache

    FQDN Check

    Enable FQDN Checking

    FQDN Default

    Default FQDN

    HTTP 302 Redirect Not Enforced List

    HTTP 302 Redirect Not-Enforced List

    HTTP 302 Redirect Replacement HTTP Code

    HTTP 302 Redirect Replacement HTTP Status Code

    HTTP 302 Redirects Enabled

    Enable HTTP 302 Redirects

    Http Only

    Enable HTTP Only Cookies

    Invert Not Enforced IPs

    Invert Not-Enforced IPs

    Invert Not Enforced URIs

    Invert Not-Enforced URIs

    JWT Cache Size

    Max Entries in JWT Cache

    Legacy User Agent Support Enable

    Enable Legacy Support Handlers

    Load Balancer Cookie Enabled

    Enable Load Balancer Cookies

    Login Form URI

    Login Form URI List

    Logout Entry URI

    Logout Entry URI Map

    Logout Introspect Enabled

    Enable Logout Introspection

    Logout Request Parameter

    Logout Request Parameter Map

    Missing PDP entry URI

    Missing POST Data Preservation Entry URI Map

    Not Enforced Client IP List

    Not-Enforced Client IP List

    Not Enforced Favicon

    Not-Enforced Favicon

    Not Enforced IP Cache Flag

    Enable Not-Enforced IP Cache

    Not Enforced IP Cache Size

    Max Entries in Not-Enforced IP Cache

    Not Enforced URIs Cache Enabled

    Enable Not-Enforced URIs Cache

    Not Enforced URIs Cache Size

    Max Entries in Not-Enforced URI Cache

    Not Enforced URIs

    Not-Enforced URIs

    PDP Cache TTL in Minutes

    POST Data Preservation Cache TTL

    PDP Maximum Cache Size

    POST Data Preservation Cache Size

    PDP Maximum Number of Cache Entries

    Max Entries in POST Data Preservation Cache

    PDP Stickysession key-value

    POST Data Preservation Sticky Session Key Value

    PDP Stickysession mode

    POST Data Preservation Sticky Session Mode

    Perform Policy Evaluation in User Authenticated Realm

    Enable Policy Evaluation in User Authentication Realm

    Policy Cache Per User

    Max Entries in Policy Cache per Session

    Policy Cache Size

    Max Sessions in Policy Cache

    Policy Evaluation Realm

    Policy Evaluation Realm Map

    Policy Set

    Policy Set Map

    Port Check Enable

    Enable Port Checking

    Port Check File

    Port Check Filename

    Port Check Setting

    Port Check Protocol Map

    Possible XSS code elements

    XSS Code Element List

    Post Data Preservation enabled

    Enable POST Data Preservation

    Pre-Authenticated Cookie Max Age

    Max Age of Pre-Authentication Cookie

    Pre-Authenticated Cookie Name

    Pre-Authentication Cookie Name

    Profile Attribute Mapping

    Profile Attribute Map

    Regular Expression Remove Query Parameters

    Regex Remove Query Parameters List for Policy Evaluation

    Remove Query Parameters

    Remove Query Parameters List for Policy Evaluation

    Resource Access Denied URI

    Access Denied URI Map

    Response Attribute Mapping

    Response Attribute Map

    Restrict To Realm

    Restrict to Realm Map

    Retain Query Parameters

    Query Parameter List for Policy Evaluation

    Rotate Local Audit Log

    Enable Local Audit Log Rotation

    Samesite Cookie Attributes Excluded User Agents Pattern List

    Exclude Agents From Samesite Cookie Attributes

    Session Attribute Mapping

    Session Attribute Map

    URL Policy Env GET Parameters

    GET Parameter List for URL Policy Env

    URL Policy Env jsession Parameters

    JSession Parameter List for URL Policy Env

    URL Policy Env POST Parameters

    POST Parameter List for URL Policy Env

    User Principal Flag

    Enable User Principal Flag

    User Token Name

    User Session Name

    XSS detection redirect URI

    XSS Redirect URI Map
    Session and OAuth 2.0 token terminology

    Sessions and OAuth 2.0 (or Open ID Connect) tokens that are stored in the CTS token store were previously referred to as CTS-based, and sessions/tokens that are returned to the client were referred to as client-based.

This release introduces new terminology to clarify and simplify the distinction between the two types of sessions and tokens, moving away from low-level descriptions to the following terms:

  • Server-side (previously called CTS-based)

  • Client-side (previously called client-based)

This change is reflected in both the documentation and the configuration settings that you see in the user interface.

Terminology for denying or allowing access

The AM 7.2 release initiates the move towards more descriptive and inclusive terminology for the concept of allowing or denying access to components or services.

Where you might previously configure a whitelist or a blacklist, you now configure an allowlist or a denylist. This renaming task is ongoing throughout the ForgeRock documentation and user interfaces.

Change in behavior when deleting UMA policies

In previous AM releases, deleting an UMA policy did not impact any nested UMA policies. In AM 7.2.0, if you delete an UMA policy, any nested UMA policies are deactivated.

For details, see Delete an UMA policy (REST).

Changes in AM 7.1
Decompressed JWTs

By default, AM rejects any JWT that expands to more than 32 KiB (32768 bytes) when decompressed. For more information about changing this default value, see Control the size of compressed JWTs.

Request Body Size

By default, AM rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size. For more information about changing this default value, see Limit the size of the request body.

Pre-Approval for Redirection URIs Enforced

This change affects AM when acting as an OAuth 2.0 and OpenID Connect client.

If a redirection URI uses a scheme, host, or port that differs from that of AM, you must now add it to the global validation service to ensure that it is pre-approved. This is described in Success and failure redirection URLs.

Otherwise, AM rejects the URI, and redirection fails.

Subject Claim in Access and ID Tokens

The subject claim of access tokens and ID tokens has changed formats to ensure that it is locally unique. The new format is not enforced after upgrading to AM 7.1, but new installations default to it.

The org.forgerock.security.oauth2.enforce.sub.claim.uniqueness advanced server property controls the format of the sub claim.

Before enabling it, ensure that your clients can use the new sub claim format, or a combination of the sub and the subname claims.

The Retry Limit Decision node

The new Save Retry Limit to User feature in this node is enabled by default after upgrade and requires upgrading the identity store schema.

Ensure you update the schema following the instructions in Upgrade AM instances, or disable the feature. ForgeRock recommends keeping it enabled for security reasons.

Failure to take any of the actions will break the authentication journey for trees using this node.

One-Time Passwords in Authentication Nodes

One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient state.

Modify any custom authentication nodes or scripts used by the Scripted Decision node to retrieve the one-time passwords from the transient state after upgrading to AM 7.1.

Changes in AM 7
User Profile Whitelist

The profile attribute allowlist controls the information returned to non-administrative users when accessing json/user endpoints.

Common profile attributes are allowlisted by default, but you need to add any custom attribute you want your non-administrative users to see. For more information, see Configure the user profile allowlist.

/json/authenticate Endpoint

When a client makes a call to the /json/authenticate endpoint appending a valid SSO token, AM returns the tokenId field empty if HttpOnly cookies are enabled. For example:

[/mnt/scratch/workspaces/workspace/am-docs-release_7.3.x/target/asciidoc/modules/ROOT/attachments/endpoints/authenticate.bash:#authenticate-expected-when-session-exists]
Secure Authentication Tree State Secret ID

An AES 256-bit key called directenctest must be available in the environment during upgrade, but it does not need to be the same key that AM provides on the default keystore.

After upgrade, ensure that the am.authn.trees.transientstate.encryption secret ID is always mapped to an existing, resolvable secret or key alias. Failure to do so may result in trees not working as expected.

The Embedded DS

The embedded DS can only be used for single AM instances, for test and demo purposes. Sites are not supported.

Sites using embedded DS servers must be migrated to external DS servers before upgrading.

SAML v2.0 Secrets

AM 7 migrated SAML v2.0 to use secret stores. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see Configure secret stores after upgrade.

goto and gotoOnFail Query Parameter Redirection

Redirection URLs for authentication services, agents, and SAML v.2.0 must be configured in Success and failure redirection URLs if they are not in the same scheme, FQDN, and port as AM, or are not relative to AM’s URL.

Web Agents of a Version Earlier than 5.6.3

Several properties that used to be configured as custom properties (com.sun.identity.agents.config.freeformproperties) have been added as regular properties. Due to this change, upgrading to AM 7 will overwrite the value of the original custom properties with the default value of the new UI properties.

To work around this issue, perform one of the following actions:

  • Upgrade to Web Agents 5.6.3 or later before upgrading to AM 7.

  • After upgrading to AM 7, reconfigure the properties that you configured as custom properties in their new UI counterparts.

Changes on the CTS Reaper Tuning Properties

AM 7 changes the way the CTS reaper searches for expired tokens.

After upgrading, retune the CTS Reaper using the information in Reaper Search Size.

OpenID Connect Clients Authenticating with JWTs

OpenID Connect clients authenticating with JWTs must include in the JWT a jti claim containing a unique identifier, in line with OpenID Connect Core 1.0 incorporating errata set 1.

Cookie Filter

AM flags cookies as secure if they come through a connection marked as secure, or if they come through HTTPS. See Secure cookie filter.

Changes in AM 6.5.0.2 and 6.5.1
OAuth 2.0 Refresh Tokens

AM only issues refresh tokens to clients that have the refresh token grant type configured in their client profile.

After an upgrade to 6.5 or later using the UI or the openam-upgrade-tool .jar file, existing OAuth 2.0 clients are configured to use all grant flows, including the Refresh Token Grant flow.

To configure the refresh token grant type manually, see To Configure AM to Issue Refresh Tokens.

Changes in AM 6.5
Recovery Codes

Recovery Codes are encrypted, and existing codes are no longer displayed to the user. For more information, see Upgrade device recovery codes.

Secret Stores

AM 6.5 introduced secret stores for OAuth 2.0 and the persistent cookie module. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For more information, see Configure secret stores after upgrade.

External Configuration Store

DS 6.5 introduced setup profiles, which pre-configure instances for different usages, such as CTS or configuration data. The default base DN for a DS configuration store instance (ou=am-config) is different to the default used by previous versions of AM (dc=openam,dc=forgerock,dc=org).

Do not run multiple instances of AM where the configuration store base DNs do not match. Use the same configuration store base DNs when configuring external DS 6.5+ instances that will be used simultaneously alongside existing DS 6 or earlier configuration store instances.

For more information, see Prepare a configuration store.

Changes in AM 6
json/ Endpoints

AM’s CSRF protection filter requires that either the X-Requested-With or the Accept-API-Version headers are included on requests to endpoints under the json root. For more information, see Reviewing REST API Versions Before Upgrading.

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:

  1. 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.

  2. 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.

  3. Deploy the new AM .war file on the rest of the AM servers.

  4. Once the site is up, and before opening the service to the end users, review the secret ID mappings of the new secret stores and make changes to them as you see fit.

    For example, the upgrade process may have created stores for features you are not using. Those may have mappings to secrets that do not exist, and you may want to remove them in production environments.

    For more information about the available secret IDs, see Secret ID Default Mappings.

    Reference: SAML v2.0 mappings after upgrade

    AM has always been very flexible regarding the configuration of secrets for SAML v2.0; this is why migrating the different combinations may create a high number of secret IDs 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 IDs. If this rule cannot be satisfied, the upgrade process creates new secretIDs for the provider by assigning it a secret ID 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 ID 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 are providing the ability for ForgeRock Authenticator users to access and view device recovery codes.

AM versions earlier than 6.5 do not 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.

  1. 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).

  2. 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.

  3. 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:

  1. 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.

  2. 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.

  3. 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 instead manually migrate from your existing deployment to a new deployment.

For complex legacy deployments, ForgeRock can assist you in the migration process.

Upgrade a legacy deployment

  1. Prepare your customized AM WAR file.

  2. Prepare a new deployment, installing servers from the new, customized WAR file, starting with the instructions in Install AM.

  3. After installation, configure the new servers in the same way as the old servers, adapting as necessary.

    You can use the ssoadm do-batch command to apply multiple changes with one command.

  4. Validate that the new service is performing as expected.

  5. Redirect client application traffic from the old deployment to the new deployment.