Requirements and Upgrade Considerations

Java and Web Containers

OpenAM 16.1.4 requires Java 11 or later. The supported LTS versions documented for this release are JDK 11, 17, 21, and 25. Choose a Java version supported by both OpenAM and your web container.

Web container	Java minimum	Notes
Apache Tomcat 10.1.x	11	Use a maintained patch release.
Apache Tomcat 11.x	17	The project Docker image uses Tomcat 11 with JRE 25.

Web container

Java minimum

Notes

Apache Tomcat 10.1.x

Use a maintained patch release.

Apache Tomcat 11.x

The project Docker image uses Tomcat 11 with JRE 25.

These requirements are recorded in the release installation prerequisites, the release Dockerfile, and the Apache Tomcat version matrix. The WAR does not supply a Java runtime.

Configure the required JVM module exports and the container’s file permissions, memory, and file-descriptor limits as described in Preparing a Java Environment and Preparing Apache Tomcat.

Policy agents have separate releases and platform requirements. The server’s container table does not describe agent compatibility. Consult the Java policy agent releases and web policy agent releases for the agent version you deploy.

Plan an Upgrade

Read the release records for every version between your installation and the target release. Test the upgrade with a copy of your configuration and data, including authentication chains, OAuth 2.0 and OIDC clients, SAML sign-on and logout, policy evaluation, agents, custom extensions, scripts, and CTS connectivity.

Back up the deployed WAR, configuration directory, keystores, configuration store, and customizations before replacing files. Retain matching pre-upgrade binaries and data for recovery. Follow the upgrade planning, backup guidance, and server upgrade procedure.

Restrict access to the upgrade interface, plan downtime, and complete the Upgrade wizard or command-line upgrade tool before returning the deployment to service. Replacing the WAR alone does not perform all configuration upgrade steps. The release history does not imply a tested direct upgrade path from every historical version.

Compatibility Checks

From 15.1.6, Oracle Directory Server Enterprise Edition is no longer supported as a configuration store. Review the release record if your deployment uses it.
From 16.0.3, the server requires Java 11 bytecode support and Jakarta EE 9 APIs. Migrate servlet-dependent custom filters, listeners, and extensions from javax.servlet to jakarta.servlet and rebuild against the target version. A Java EE container such as Tomcat 9 cannot deploy this WAR unchanged. See the 16.0.3 release record.
From 16.1.1, the XUI supports an HttpOnly session cookie. Review custom JavaScript that reads the session cookie; use the documented REST interfaces when the cookie is HttpOnly. Legacy Liberty SOAP services also have new opt-in and authentication requirements; see the server upgrade notes.
From 16.1.2, IdP discovery endpoints accept relative and same-origin return URLs; other destinations must match org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist (a semicolon-separated list of URL patterns, empty by default). For endpoints hosted by OpenAM, configure this advanced server property as described in Modifying a Circle of Trust’s Configuration and the server upgrade notes. Review security advisories for additional changes to server-side URL fetching, script execution, and class instantiation.

For a standalone IDP Discovery WAR, set the same property in $HOME/libIDPDiscoveryConfig.properties, where $HOME is the home directory of the user running the web container, and restart the discovery application.
From 16.1.3, the configuration upgrade adds missing ScriptingService sub-configurations, including the access token modification script introduced in 16.1.1. Run the upgrade step before using that script. Legacy Liberty ID-FF endpoints also require explicit configuration and message signing; see the release record and the server upgrade notes.
In 16.1.4, empty redirect allowlists no longer permit arbitrary external destinations. Populate Valid goto URL Resources and the federation return URL lists for legitimate cross-domain redirects. See Valid goto URL Resources and RelayState URL List.
The 16.1.4 upgrade deactivates built-in identities that remain active with their shipped passwords. Set deployment-specific passwords and reactivate only the identities you require. Authentication defaults on a new installation differ from those preserved on upgrade; see Authentication Defaults.
For 16.1.4, merge the CSRF token handling into customized device authorization pages. Custom clients must send consent decisions in the POST body; links appending user_code to the verification URI no longer prefill the code. See the device form changes, verification URI changes, and consent submission changes.

Known Issues and Help

The issue tracker records reported problems and ongoing work. Read each issue’s affected versions, reproduction, and linked fixes before deciding whether it applies to your deployment. Consult the published security advisories separately for security information and follow-up fixes.

For usage questions, use the community discussions. Include the OpenAM, Java, and container versions, relevant configuration, reproduction steps, and sanitized logs in a bug report. Follow the project’s security policy to report a suspected vulnerability.