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

During the upgrade process, you must take the OpenAM servers in the site out of production, instead redirecting client application traffic elsewhere. This is required because upgrade involves making changes to OpenAM'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 OpenAM server .war file.

2. Back up the deployment.

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

4. For servers in the site, stop OpenAM, or if necessary stop the container where OpenAM runs.

5. For servers in the site, 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. For servers in the site, restart OpenAM or the container where it runs.

7. For the first server in the site, follow the instructions in the Upgrade Wizard.

   Alternatively for a silent, unattended upgrade, you can use the openam-upgrade-tool-13.0.0.jar tool to upgrade the server configuration in a command-line script.

   First you must install the tool. The procedure, Procedure 3.2, "To Set Up Configuration Tools" in the Installation Guide, describes how to install the tool.

   The upgraded server must be deployed and running when you use the tool.

   The openam-upgrade-tool-13.0.0.jar relies on a properties file to upgrade OpenAM server.

   $ cp sampleupgrade upgrade.properties
   $ vi upgrade.properties
   $ grep -v "^#" upgrade.properties
   SERVER_URL=http://openam.example.com:8080
   DEPLOYMENT_URI=/openam
   ACCEPT_LICENSES=true

   When the new OpenAM server .war file is deployed and running, you can upgrade by using the tool with the properties file.

   $ java -jar openam-upgrade-tool-13.0.0.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.

8. (Optional) If you installed OpenAM using an external directory server as the configuration store, add an access control instruction (ACI) to the external directory to give the OpenAM 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 Section 1.5, "Preparing an External Configuration Data Store" in the Installation Guide for more information about using an external directory server as the OpenAM configuration store.

9. (Optional) If you want to configure the upgraded system for the Core Token Service (CTS), read Chapter 6, "Configuring the Core Token Service" in the Installation Guide. For a list of supported directory services, see the Section 2.4, "Data Store Requirements" in the Release Notes

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

    Referrals found that require removing 

    OpenAM will take the following actions during the upgrade:

    • Removing all referral policies from your OpenAM configuration.

    • Copying resource types and policy sets associated with removed referral policies to the realms targeted by the referral policies.

    For example, suppose you had an OpenAM 12 deployment with a referral policy in realm A, and that referral policy referred to policies in realm B. During an upgrade, OpenAM would delete the referral policy in realm A and copy all the resource types and policy sets associated with the deleted referral policy from realm A to realm B.

    After upgrading to OpenAM 13, you are responsible for reconfiguring OpenAM 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 policy agent with the realm and policy set ^[1] that contain policies to be evaluated when that agent requests a policy decision from OpenAM. Previously, you might have configured the agent to use a realm that contained a referral policy. Because referral policies are not supported in OpenAM 13, this is no longer possible.

      For more information about configuring an agent with a realm and policy set, see Section 4.2, "Working With Realms and Policy Agents" in the Administration Guide.

    • Copying or moving a policy or a group of policies. OpenAM 13 has new 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 Section 2.1.2.6.6, "Copying and Moving Policies" in the Developer's Guide.

11. Validate that the service is performing as expected.

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

After upgrade from OpenAM 11.0.x, all OAuth 2.0 client configurations inherit the default response types:

1. For each OAuth 2.0 client configuration, edit the list of response types to remove any that are not supported or not required.

2. For each OAuth 2.0 client configuration, update the client password.

   As part of a fix for OpenID Connect ID Token signing, the password storage format for OAuth 2.0 clients has changed. OpenAM now stores client passwords using reversible encryption. OpenAM 11.0 stores client passwords using a one-way hash algorithm, and therefore the passwords cannot be recovered.

   You can update the client password by using either OpenAM console or the ssoadm update-agent command with the --attributevalues option to update the value of the userpassword attribute.

1. Prepare your customized OpenAM server .war file.

2. Prepare a new deployment, installing servers from the new, customized .war file, starting with the instructions in Chapter 2, "Installing OpenAM Core Services" 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.

1. Back up the policy agent installation and configuration directories.

   Also back up the configuration if it is stored centrally in OpenAM.

2. Redirect client traffic away from the protected application.

3. Stop the web server where the policy agent is installed.

4. Remove the old policy agent as described in the OpenAM Web Policy Agent User's Guide.

   If the uninstallation process has changed, refer to the version of the Web Policy Agent Installation Guide that corresponds to your web policy agent.

5. Install the new policy agent using the existing configuration.

6. Start the web server where the policy agent is installed.

   For new features, the policy agent uses the default configuration until you make changes.

7. Validate that the policy agent is performing as expected.

8. Allow client traffic to flow to the protected application.

1. Back up the policy agent installation and configuration directories.

   Also back up the configuration if it is stored centrally in OpenAM.

2. Redirect client traffic away from the protected application.

3. Uninstall the old policy agent.

4. Install the new policy agent.

   For new features, the policy agent uses the default configuration until you make changes.

5. Validate that the policy agent is performing as expected.

6. Allow client traffic to flow to the protected application.

Since OpenAM 10.1, the session tools are no longer needed. Upgrading other tools consists of installing new tools and customizing tools scripts as necessary.

1. Install new versions of the tools.

2. Apply any customizations you made to the scripts, referring to the old tools installation as necessary.

3. Once the new tools are working, you can delete the old tools.