Chapter 2. Upgrading OpenAM Servers

This chapter covers upgrade from OpenAM core server 9.5 or later to the current version. For other OpenAM components, see Upgrading OpenAM Components.

OpenAM server upgrade relies on the Upgrade Wizard to make the necessary changes to the configuration store. You must then restart OpenAM or the container in which it runs. Even a version number change requires that you run the Upgrade Wizard, so needing to run the Upgrade Wizard says nothing about the significance of the changes that have been made to OpenAM. You must run the Upgrade Wizard even for maintenance releases.

Make sure you try upgrading OpenAM in a test environment before applying the upgrade in your production environment.

Procedure 2.1. To Upgrade From OpenAM 9.5 or Later

Follow these steps to upgrade a site of OpenAM servers (version 9.5 or later). 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, you can use the command-line tool to upgrade the server configuration. The procedure, To Set Up Configuration Tools, describes how to install the tool.

  8. If you want to configure the upgraded system with a different directory service for the Core Token Service (CTS), read Configuring the Core Token Service.

  9. Validate that the service is performing as expected.

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

Procedure 2.2. To Complete Upgrade from OpenAM 10.1.0 Xpress

When upgrading from OpenAM 10.1.0 Xpress, the upgrade tool does not change the Dashboard service LDAP schema, although the object IDs used in the Dashboard service LDAP schema definitions are not correct.

You can fix the object IDs manually using the OpenDJ ldapmodify command. The command is delivered with OpenDJ directory server.

  1. Update the LDAP schema defined in the OpenDJ directory server where OpenAM stores its configuration.

    Make the change on one of the replicated OpenDJ configuration directory servers.

    The example command shown below uses the ldapmodify command delivered with the embedded OpenDJ configuration directory server for OpenAM with deployment URI /openam. When you use the embedded OpenDJ configuration directory server, the password for the cn=Directory Manager account is the same password used by amadmin.

    The LDAP schema definitions are stored on the LDAP subentry with distinguished name cn=schema. You use the following LDIF format definitions to correct the object IDs in the definitions.

    $ cd ~/openam/opends/bin
    $ cat dash.ldif
    dn: cn=schema
    changetype: modify
    delete: objectClasses
    objectClasses: ( 1.3.6.1.4.1.1466.101.120.1433 NAME
      'forgerock-am-dashboard-service' AUXILIARY MAY (
       assignedDashboard ) X-ORIGIN 'Forgerock' )
    -
    delete: attributeTypes
    attributeTypes: ( 1.3.6.1.4.1.36733.2.1.9.2.811 NAME ( 'assignedDashboard' )
      DESC 'Dashboard App registry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
      X-ORIGIN 'OpenAM' )
    -
    add: attributeTypes
    attributeTypes: ( 1.3.6.1.4.1.36733.2.2.1.3.1 NAME ( 'assignedDashboard' )
      DESC 'Dashboard App registry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
      X-ORIGIN 'OpenAM' )
    -
    add: objectClasses
    objectClasses: ( 1.3.6.1.4.1.36733.2.2.2.3.1 NAME
      'forgerock-am-dashboard-service' AUXILIARY MAY (
      assignedDashboard ) X-ORIGIN 'Forgerock' )
    
    $ ./ldapmodify -p 50389 -D "cn=Directory Manager" -w password -f ./dash.ldif
    Processing MODIFY request for cn=schema
    MODIFY operation successful for DN cn=schema
  2. If you want to configure the upgraded system with a different directory service for the Core Token Service (CTS), read Configuring the Core Token Service.