PingAM 8.0.0

Upgrade AM instances

To upgrade an AM deployment, you must upgrade each server instance in your site by upgrading the AM software on each server. You only need to upgrade the configuration on one server in the site.

  • AM 8 supports Apache Tomcat 10 as a web application container. If you use Apache Tomcat, you must upgrade to at least version 10 before you upgrade to AM 8.

  • AM 8 supports a file-based configuration store (FBC) in production deployments. If you migrate your configuration to FBC, there is no longer the concept of separate sites. Each server has its own ID and its own local configuration. Learn more in FBC and AM sites.

High-level upgrade steps

Upgrading AM involves the following high-level steps:

On one server in your site

  1. If you use Apache Tomcat as an application container:

    1. Stop AM or the container where it runs.

    2. Upgrade Tomcat.

  2. Upgrade the AM server software.

    The server is upgraded when you deploy the .war file of the new version. You must deploy the new .war file on each server in the site.

  3. Upgrade the configuration.

    Use one of the following methods:

    • amupgrade

      This utility is provided in the AM-8.0.0.zip file and upgrades a configuration exported using Amster. This is the recommended way to update the configuration.

    • Upgrade wizard

      The upgrade wizard is launched when you replace a deployed AM .war file with a newer version, then go to the deployment URL.

    • openam-upgrade-tool

      The openam-upgrade-tool-14.1.3.28.jar is installed when you set up the configuration tools.

    You can’t upgrade the configuration by deploying a new version and then using ssoadm import-svc-config to import an existing configuration.

  4. Update the schema

    Generally, the configuration store schema is updated when you update the configuration. From time to time, updates are required to the schema of other datastores, such as the identity store or the CTS store. You must make these updates manually.

    Learn more in Update the schema.

  5. Update tools and scripts.

    Read the Release notes to understand the changes introduced in each version before you update AM tools and scripts.

  6. Restart AM or the container where it runs.

On the remaining servers in your site

  1. If you use Apache Tomcat as an application container:

    1. Stop AM or the container where it runs.

    2. Upgrade Tomcat.

  2. Upgrade the AM server software.

    The server is upgraded when you deploy the .war file of the new version. You must deploy the new .war file on each server in the site.

  3. Restart AM or the container where it runs.

If you’re upgrading to AM 8 from an unsupported version of AM, you might need to upgrade to a supported version first, and then to AM 8.

Before you upgrade

You must follow these steps before you start an upgrade.

  1. Plan your upgrade.

  2. Prepare a customized AM .war file.

  3. Back up your deployment.

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

  5. Make the transient state encryption key available to all instances in the site.

    An AES 256-bit key called directenctest must be available to all instances in the site. This might mean, for example, copying the keystore across the site.

    This key doesn’t need to be the same key that AM provides in the default keystore.

    If you don’t provide this key, AM won’t start up after the upgrade.

    What is the directenctest key for?

    AM uses the directenctest key to encrypt information stored in the transient state of authentication trees.

    The upgrade process maps this key to the am.authn.trees.transientstate.encryption secret label.

    How do I make the directenctest key available?

    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 house this secret, or you can add it to one of your existing stores.

    + The following example creates 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?

    The passwords are stored as secrets in a separate secret store. For example, a file system volume secret store.

    After the upgrade, you can rename the key alias or set a different key in the secret label mapping. Make sure the secret label is always mapped to an existing, resolvable secret or key alias.

Upgrade Tomcat

AM 8 supports Apache Tomcat 10.x and removes support for earlier Tomcat versions. If you use Apache Tomcat as an application container, you must install Apache Tomcat 10.x and deploy AM 8 into that container. Running AM 8 in an Apache Tomcat 8.5 or 9 container does not work.

In addition to downloading and installing Apache Tomcat 10.x, make the following changes before you deploy AM:

  • Update any custom scripts, configurations, and allowlist entries to reflect the change to Jakarta EE 9 (Servlet API 5.0). In particular, change the following references:

    • javax.servlet → jakarta.servlet

    • javax.websocket → jakarta.websocket

    You don’t need to change other javax references, such as javax.xml and javax.inject.

  • The Tomcat system property to manage encoded slash (/) characters in requests has changed.

    The org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH property has been removed in Tomcat 10 and replaced with the encodedSolidusHandling property.

    Update references to the old property in the Connector element in your Tomcat server.xml file.

    In production environments, avoid resource names that contain forward slashes.

Upgrade the server and configuration

Use one of the following methods to upgrade the AM server software and configuration:

amupgrade

The amupgrade utility converts a set of exported AM configuration files so that the configuration can be used with the latest AM version. Use this utility with Amster and to upgrade file-based configurations. The utility has the same Java requirements as Amster. Learn more in the Amster Release notes.

amupgrade rules

The amupgrade utility uses upgrade rules to convert configuration between versions.

The upgrade rules are sequential, that is, they upgrade configuration from one version to the next minor consecutive version. If you’re upgrading to a version greater than the next minor consecutive version, you must run multiple amupgrade commands sequentially until you reach the required configuration.

In other words, if you’re upgrading your configuration from version 7.2.x to version 8.0.x:

  1. Run amupgrade with the 7.2.x-to-7.3.x.groovy rules file to get a 7.3 configuration.

  2. Run amupgrade on the 7.3 configuration with 7.3.x-to-7.4.x.groovy rules file to get a 7.4 configuration.

  3. Continue running successive upgrades until you have an 8.0 configuration.

You can’t use amupgrade to upgrade a running AM instance.

Before you start

  1. Download the AM .zip file from the Backstage download site.

  2. Extract the contents of the .zip file.

  3. In the extracted directory, locate the Config-Upgrader-8.zip file.

  4. Extract the Config-Upgrader-8.zip file.

Upgrade from an Amster configuration export

  1. Follow the Amster documentation to export your configuration.

  2. Upgrade the exported configuration to the new version:

    $ amupgrade \
-i exported configuration \
-o output directory \
-a amster version \
rules/amster/from-to-to.groovy

    Where:

    • exported configuration is the path to the configuration directory you generated in step 1

    • output directory is the directory to which the command writes the upgraded configuration

    • amster version is the version of Amster you will use to import the configuration

    • from is the AM version from which you’re upgrading

    • to is the AM version to which you’re upgrading

    • rules specifies the path to a configuration rules file in the /path/to/amupgrade/rules directory

    For example:

    $ amupgrade \
-i /path/to/AM7.5Config/ \
-o /path/to/AM8Config \
-a 8.0 \
rules/amster/7.5.x-to-8.0.x.groovy
Reading existing configuration from files in /path/to/AM7.5-config/…​
Modifying configuration based on rules in [rules/amster/7.5.x-to-8.0.x.groovy]…​
reading configuration from Amster json files
Writing configuration to new location at /path/to/AM8Config…​
Upgrade Completed, modified configuration saved to /path/to/AM8Config
    If you are upgrading a file-based configuration, rather than a configuration exported with Amster, use the --fileBasedMode option instead of the -i and -o options.

  3. Install a new version of DS with an am-config profile.

    Don’t upgrade or use an existing DS configuration store because configuration associated with the older DS version can cause conflicts.

  4. Stop AM or the container where it runs.

  5. Unconfigure AM by removing the configuration files in the $HOME directory of the user running the web application container.

    For example:

    $ rm -rf $HOME/am $HOME/.openamcfg

    To uninstall AM and its associated configuration files, delete the following directories:

    • The configuration directory.

      If you didn’t use the default configuration location ($HOME/am), check the value of the Base installation directory property under Deployment > Servers > Server Name > General > System.

    • The hidden directory that holds a file pointing to the configuration directory.

      For example, if you are using Apache Tomcat as the web container, this file could be $HOME/.openamcfg/AMConfig_path_to_tomcat_webapps_am_.

  6. Undeploy the AM web application.

    For example, if you are using Apache Tomcat as the web container, remove the .war file and expanded web application from the container:

    $ cd /path/to/tomcat/webapps/
$ rm -rf am.war am/

  7. Upgrade Tomcat.

  8. Install the new version of AM using the new DS server for your configuration store.

  9. Follow the Amster documentation to import the upgraded configuration.

  10. Restart AM or the container where it runs.

Upgrade wizard

The upgrade wizard brings the AM configuration, including the version number, up to date with the new version.

  1. Stop AM or the container where it runs.

  2. Deploy your customized AM .war file.

    When you deploy the new .war file, you might need to delete working files left by the old deployment.

    For example, if you deploy on Apache Tomcat, replace /path/to/tomcat/webapps/am.war with the customized .war file, then recursively delete the /path/to/tomcat/webapps/am/ and /path/to/tomcat/work/Catalina/localhost/am/ directories before restarting the server.

  3. Restart AM or the container where it runs.

  4. 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. After the upgrade is complete, AM prevents access to the upgrader UI.

  5. Go to the deployment URL and follow the prompts to upgrade.

  6. Restart AM or the container where it runs.

  7. Update the identity store schema:

    1. Log into AM.

    2. Go to Realms > Realm Name > Datastores > External User Store.

    3. Click Load Schema then click Save to apply your changes.

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

  • 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 won’t affect your installed instance.

    You must also remove the references to click-servlet from the deployment descriptor file. Edit /path/to/tomcat/webapps/am/WEB-INF/web.xml to remove the following mappings:

    <servlet>
    <servlet-name>click-servlet</servlet-name>
    <servlet-class>org.apache.click.ClickServlet</servlet-class>
</servlet>

...

<servlet-mapping>
    <servlet-name>click-servlet</servlet-name>
    <url-pattern>*.htm</url-pattern>
</servlet-mapping>

openam-upgrade-tool

The openam-upgrade-tool lets you upgrade the configuration without user intervention.

  1. Stop AM or the container where it runs.

  2. Deploy your customized AM .war file.

    When you deploy the new .war file, you might need to delete working files left by the old deployment.

    For example, if you deploy on Apache Tomcat, replace /path/to/tomcat/webapps/am.war with the customized .war file, then recursively delete the /path/to/tomcat/webapps/am/ and /path/to/tomcat/work/Catalina/localhost/am/ directories before restarting the server.

  3. Restart AM or the container where it runs.

  4. Set up the configuration tools to install the openam-upgrade-tool-14.1.3.28.jar.

    A sampleupgrade file is expanded in the directory where you install the tool.

  5. Create a configuration file, for example, upgrade.properties.

    You can use the sampleupgrade file as a template.

    The upgrade configuration file should resemble the following:

    $ grep -v "^#" upgrade.properties
SERVER_URL=https://am.example.com:8443
DEPLOYMENT_URI=/am
ACCEPT_LICENSES=true

  6. Run the upgrade tool, specifying the upgrade.properties file you created:

    $ java -jar openam-upgrade-tool-14.1.3.28.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.
Updating Platform Properties; Done.
Writing Upgrade Log; Done.

Upgrade Complete.

    You can find more information about openam-upgrade-tool-14.1.3.28.jar in the reference documentation.

  7. Restart AM or the container where it runs.

Update tools, scripts, and components

  1. Update the AM tools.

    Follow Set up administration tools and the Amster User Guide to install an updated version of the tools.

    When you have confirmed the new tools are working, delete the old tools.

  2. Make sure the AM scripts are current and contain the modifications your environment requires.

    To avoid overwriting changes made in customized scripts, the upgrade process doesn’t update scripts from earlier versions of AM.

    Check the scripts in your environment are compatible with the version of AM you’re upgrading to by following these steps:

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

    2. Install an AM 8 test environment, and compare the scripts.

      New installations always have the current scripts.

  3. Review the information in Upgrade components and services and decide if you need to reconfigure any of AM’s services or features.

    Reconfigure any custom advanced properties if necessary. These properties are lost during the upgrade, and you’ll need to re-add them in the AM admin UI.

    How do I configure advanced server properties?

    • To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI.

    • 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 already configured, click on the pencil () button to edit it. When you are finished, click on the tick () button.

    Click Save Changes.

Update the schema

You might need to update the schema for specific datastores, depending on the version from which you are upgrading and the datastore type.

Configuration store

Generally, updating your configuration makes the required schema updates to the configuration store.

After you’ve updated the configuration, 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=am,ou=admins,dc=example,dc=com");)

You can find more information about configuring AM configuration stores in Prepare configuration stores.

Identity store

Depending on the version you’re upgrading from, and the features you’ve configured, you might need to update your identity store schema manually.

Upgrade from AM 7.0 with a PingDS identity store

  1. In the path where you deployed the am.war file (for example, /path/to/tomcat/webapps/am) locate the following file in the WEB-INF/template/ldif/opendj directory:

    opendj_retry_limit_node_count.ldif

  2. Update the identity store schema as follows:

    $ /path/to/opendj/bin/ldapmodify \
--hostname 'ds.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_retry_limit_node_count.ldif

    This schema update is required for the Save Retry Limit to User feature in the Retry Limit Decision node. The feature is enabled by default.

    Even if you aren’t currently using the Retry Limit Decision node, you should make this schema update, in case you decide to use the node in the future. If you can’t update the identity store schema at this point, you must disable the feature.
Using push or web authentication, or using the Ping SDKs for device profiling

Apply the following LDIF files:

  • /path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif

  • /path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif

For example:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'ds.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif \
/path/to/tomcat/webapps/am/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif

If you don’t make this schema change, you must remove the webauthnDeviceProfilesContainer object class from the user configuration after the upgrade:

  1. In the AM admin UI, go to Realms > Realm Name > Identity Stores > Identity Store Name.

  2. On the User Configuration tab, remove webauthnDeviceProfilesContainer from the LDAP User Object Class.

  3. Save your changes.

Make the same change for each identity store that doesn’t have the schema change, and in each realm that uses the identity store.

After upgrade

  1. Validate the service is performing as expected.

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