Upgrading AM Instances

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

1. Ensure you have read Planning the Upgrade 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. Ensure that an AES 256-bit key called directenctest is available to all the instances in the site. It does not need to be the same key that AM provides on the default keystore.

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

   What Is this Key for?

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

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

   The way you make the alias available depends on the version of AM you are upgrading from:

   • Versions of AM Earlier than 6.5

     The key alias must exist in the keystore configured as the AM keystore. Check the path where the keystore and its files are configured by going to Configure > Server Defaults > Security > Key Store.

   • AM 6.5

     The alias must exist in a secret store configured globally, so that all realms can access it. You can configure additional secrets by realm if required after the upgrade.

     You can create a new secret store to provide this secret, or you can add it to one of your existing stores.

   The following is an example of how to create the key alias in the AM keystore, or in a keystore configured in a secret store:

   $ keytool \
   -genseckey \
   -alias directenctest \
   -keyalg AES \
   -keysize 256 \
   -storetype JCEKS \
   -keystore /path/to/keystore.jceks

   Where Do I Find the Keystore Passwords?

   • (AM versions earlier than 6.5) The passwords are stored in the files configured in Configure > Server Defaults > Security > Key Store.

   • (AM 6.5) The passwords are secrets provided by a different secret store. For example, a file system volume secret store.

   Make sure that the alias is available to all instances of the site. This may mean, for example, copying the keystore across the site.

   After the upgrade, you can rename the key alias or configure a different key in the secret ID mapping, but ensure that this secret ID is always mapped to an existing, resolvable secret or key alias.

6. Stop AM or the container where it runs.

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

8. Restart AM or the container where it runs.

9. You must update the identity store XML schema if you are upgrading from a version of AM earlier than 6 and any of the following statements are true:

   • You have configured knowledge-based (KBA) user self-service questions.

   • You have not configured User Self-Service yet, but you added the user_store_type_kba.ldif schema to your external user data store when you configured it.

     For more information about LDIFs, see "Supported LDIF Files".

   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:

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

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

    Note

    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:

    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:

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

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

      Important

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

        Suspend any external network access to the application container until the upgrade is complete. When complete, AM prevents access to the upgrader UI itself.

      • The AM upgrade wizard uses three libraries that should be removed after upgrade, for security reasons.

        When your upgrade is complete, remove the following .jar files from the WEB-INF/lib directory:

        • click-extras-2.3.0.jar

        • click-nodeps-2.3.0.jar

        • velocity-1.7.jar

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

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

      1. Install the openam-upgrade-tool-14.1.3.19.jar tool as described in "To Set Up the Configuration Tools". A sampleupgrade file will be expanded in the directory where you install the tool.

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

      4. Restart AM or the container where it runs.

12. 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");)

    See "Preparing Configuration Stores" for more information about configuring AM configuration stores.

13. Update the identity 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 user stores, repeat the previous steps for each user store.

    Tip

    If you need to manually update your identity store user schema, see "Updating the Schema in an External Identity Repository".

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

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

    • cts-add-ttlexpire.ldif

    If you are updating from a version prior to AM 6, also apply the following LDIF files:

    • cts-add-multivalue.ldif

    • cts-add-multivalue-indices.ldif

      Note

      Replace the @DB_NAME@ variable inside the cts-add-multivalue-indices.ldif file with the CTS backend name. For example, replace occurrences of @DB_NAME@ with ctsStore.

    For example:

    $ /path/to/opendj/bin/ldapmodify \
    --hostname 'cts.example.com' \
    --port 1636 \
    --useSsl \
    --usePkcs12TrustStore /path/to/opendj/config/keystore \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
    --continueOnError \
    --bindDN uid=admin \
    --bindPassword str0ngAdm1nPa55word \
    /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-multivalue.ldif \
    /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-multivalue-indices.ldif \
    /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-ttlexpire.ldif

15. (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/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

    Important

    If you do not apply these schema changes, remove the webauthnDeviceProfilesContainer object 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 webauthnDeviceProfilesContainer from 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".

16. (Optional) Install a new version of the AM tools as described in Setting Up Administration Tools and in the ForgeRock Identity Platform Amster User Guide.

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

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

    Note

    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 in the AM Admin UI for all AM instances, go to Configure > Server Defaults > Advanced.

    • 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 not already configured, add it with its value, then click on the plus () button.

    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.

    Save your changes.

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

    To avoid overwriting changes done to the original files, the upgrade process does not update scripts from earlier versions of AM. Ensure that the scripts in your environment are compatible with the version of AM you upgraded to by performing the following steps:

    1. Read the release notes for information about possible changes.

    2. Install an AM 7.1.4 test environment, and compare the scripts. New installations always have the current scripts.

19. Validate that the service is performing as expected.

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