This guide shows you how to upgrade ForgeRock® Access Management. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

Follow these steps to upgrade a site of instances. For information on the versions that are supported for upgrade, see "Supported Upgrade Paths" in the Release Notes.

1. Ensure you have read Chapter 1 and planned your upgrade accordingly.

2. Prepare your customized AM server .war file. For more information, see "Customizing Before Upgrading".

3. Back up your deployment. For more information, see "Backing Up the Deployment".

4. Route client application traffic to another site during the upgrade. For more information, see "Routing Around Servers During Downtime".

5. Stop AM or the container where it runs.

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

7. Restart AM or the container where it runs.

8. You must update the identity store XML schema if you are upgrading from OpenAM or 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 "Supported LDIF Files" in the Installation Guide.

   • You are using the embedded DS instance as a user store.

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

   1. Change directories to the path where you have deployed the openam.war file. For example, /path/to/tomcat/webapps/openam.

   2. Locate the following files in the WEB-INF/template/ldif/opendj path:

      • opendj_add_kba_attempts.ldif

      • opendj_update_aci_kba_attempts.ldif

      Note

      If your user data store is not DS, use these files as examples to create files suitable for your environment.

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

   4. Update the user data store schema with the two files. For example, to update a DS instance, run the following command:

      $ ldapmodify \
       --hostname opendj.example.com \
       --port 1389 \
       --bindDN 'cn=Directory Manager' \
       opendj_add_kba_attempts.ldif opendj_update_aci_kba_attempts.ldif
      Password for user 'cn=Directory Manager':
      
       # 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.

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

   Note

   This step is required to use the Save Retry Limit to User feature in the "Retry Limit Decision Node" in the Authentication and Single Sign-On Guide, which is disabled by default.

   The new functionality is not enabled by default because it requires schema changes to the identity store. But, ForgeRock recommends that you enable it to harden the security around this node.

   To enable the Save Retry Limit to User feature, first apply the schema changes in the opendj_retry_limit_node_count.ldiffile to the identity store. Then reconfigure the "Retry Limit Decision Node" in the Authentication and Single Sign-On Guide.

   If you cannot update the identity store schema at this point, you should leave the feature disabled until a time when this can be actioned.

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

   1. Change directories to the path where you have deployed the openam.war file. For example, /path/to/tomcat/webapps/openam.

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

   3. Update the identity store schema. For example:

      $ ./ldapmodify \
      --hostname 'id.example.com' \
      --port 1389 \
      --continueOnError \
      --bindDN 'cn=Directory Manager' \
      /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_retry_limit_node_count.ldif
      Password for user 'cn=Directory Manager':

10. 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:443/openam, and follow the instructions in the Upgrade Wizard for an interactive upgrade.

      Important

      • After deploying AM, but before upgrade, your application container serves AM's upgrader user interface.

        You should 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 two Apache libraries that should be removed after the 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

        These files are used only by the install and upgrade wizards. Removing them will have no effect on your installed instance.

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

      1. Install the openam-upgrade-tool-14.1.2.24.jar tool as described in "Setting up Configuration Tools" in the Installation Guide. A sampleupgrade file will be expanded in the directory where you install the tool.

      2. Create a configuration file for the openam-upgrade-tool-14.1.2.24.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

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

         $ java -jar openam-upgrade-tool-14.1.2.24.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(1) in the Reference.

      4. Restart AM or the container where it runs.

11. (Optional) If you installed AM using an external directory server as the configuration store, add an access control instruction (ACI) to the external 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");)

    See "Preparing Configuration Stores" in the Installation Guide for more information about using an external directory server as the AM configuration store.

12. (Optional) If you installed AM using an external directory server as the user store, update the user store schema as follows:

    1. Log into AM.

    2. Navigate to Realm Name > Datastores > External User Store.

    3. Click Load Schema before saving, and then click Save to apply your changes.

    4. If you have additional external user stores, repeat the previous steps for each user store.

13. (Optional) If you are using an external Core Token Service (CTS) token store, update the schema by applying the following LDIF files to it:

    • cts-add-multivalue.ldif

    • cts-add-multivalue-indices.ldif

      Note

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

    • cts-add-ttlexpire.ldif

    For example:

    $ ./ldapmodify \
    --hostname 'config.example.com' \
    --port 1389 \
    --useStartTLS \
    --trustAll \
    --continueOnError \
    --bindDN 'cn=Directory Manager' \
    --bindPassword 'str0ngEx4mplePa55word' \
    /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

14. If you are using an external identity store, and intend to use push or web authentication, update the schema by applying the following LDIF files to it:

    • push_2fa.ldif

    • opendj_webauthndevices.ldif

    For example:

    $ ./ldapmodify \
    --hostname 'id.example.com' \
    --port 1389 \
    --useStartTLS \
    --trustAll \
    --continueOnError \
    --bindDN 'cn=Directory Manager' \
    --bindPassword 'str0ngEx4mplePa55word' \
    /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/push_2fa.ldif \
    /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif

    Important

    If you do not apply these schema changes, after upgrading AM you should remove the webauthnDeviceProfilesContainer object class from the user configuration.

    In the AM console, navigate to Realms > Realm Name > Identity Stores > Identity Store Name. On the User Configuration tab, remove webauthnDeviceProfilesContainer from the LDAP User Object Class property, and then save your changes.

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

    For more information on these LDIF files, and the equivalent files for supported directory servers, see "Supported LDIF Files" in the Installation Guide.

15. (Optional) Install a new version of the AM tools as described in "Installing and Using the Tools" in the Installation Guide and in the ForgeRock Identity Platform Amster User Guide.

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

16. Review the information in "Upgrading Components and Services" and decide if you need to reconfigure any of AM's services or features.

17. 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 6.5 test environment, and compare the scripts. New installations always have the current scripts.

18. Validate that the service is performing as expected.

19. Allow client application traffic to flow to the upgraded site.

1. Prepare your customized AM server .war file.

2. Prepare a new deployment, installing servers from the new, customized .war file, starting with the instructions in "Installing and Starting Servers" in the Installation Guide.

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.