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

During the upgrade process, you must take the AM servers in the site out of production, instead redirecting client application traffic elsewhere. This is required because upgrade involves making changes to AM's configuration model. If the upgrade fails, you must be able to roll back before the configuration changes impact other sites.

1. Prepare your customized AM server .war file.

2. Back up your deployment.

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

4. Stop AM or the container where it runs.

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

6. Restart AM or the container where it runs.

7. (Optional) You must update the user 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.

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

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

     1. Install the openam-upgrade-tool-14.1.1.5.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.1.5.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.1.5.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.

9. (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 an External Configuration Data Store" in the Installation Guide for more information about using an external directory server as the AM configuration store.

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

11. (Optional) If you want to configure the upgraded system for the Core Token Service (CTS), you need to import two schema files for proper CTS operation:

    • cts-add-multivalue.ldif

    • cts-add-multivalue-indices.ldif

    For more information, read "Supported Scripts" in the Installation Guide. For a list of supported directory services, see the "Data Store Requirements" in the Release Notes.

12. Referral policies are not supported in AM 6. If your deployment has referral policies, the following warning message will appear when you upgrade your server to AM 6:

    Referrals found that require removing

    Specifically, if your deployment has policies in a sub-level realm that uses a referral in the top level realm, the upgrade process will fail. You must manually delete referrals and policies from your configuration after making note of your current policies. Then, run the upgrade.

    Note

    Simply disabling the referrals and running the upgrade will also result in a failure. You must delete the referrals and policies manually.

    After upgrading to AM 6, you are responsible for reconfiguring AM, so that policy evaluation that previously depended upon referrals continues to function correctly. You might need to take one or both of the following actions:

    • Reconfiguring your web or Java agent with the realm and policy set that contain policies to be evaluated when that agent requests a policy decision from AM. For more information about configuring an agent with a realm and policy set, see "Working With Realms and Access Management Agents" in the Setup and Maintenance Guide.

    • Copy or move a policy or a group of policies. AM 6 has REST API endpoints that let you copy and move policies. This functionality might be helpful when migrating away from policy deployments that use referral policies. For more information about the REST endpoints that let you copy and move policies, see "Copying and Moving Policies" in the Authorization Guide.

13. If you have post authentication plugins that expect state to be maintained by AM between login and logout, you must rewrite and redeploy them.

    In versions prior to AM 5, the Keep Authentication Module Objects for Logout Processing option was available in the Core Authentication module. This option, when enabled, directed AM to maintain state information in server memory throughout a session's duration for post authentication plugin module instances. When logout was triggered, AM invoked the same post authentication plugin module instance, with state information intact. Therefore, developers could access module state stored at login when users logged out.

    AM 6 does not maintain state in post authentication plugins between login and logout. Post authentication plugins that rely on module state being maintained in AM's memory between login and logout must be rewritten. You can store any information that you want to save between login and logout in a session property. AM stores session properties in the CTS token store after login, and retrieves them from the token store as part of the logout process.

    To set a session property, call the setProperty method on an SSOToken object as demonstrated by the post authentication plugin sample code in "Building Your Sample Post-Authentication Plugin" in the Authentication and Single Sign-On Guide.

14. Validate that the service is performing as expected.

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

If you configured one or more JDBC audit event handlers in OpenAM 13.0.x, 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.

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.