Java 8 to OpenJDK 11 Migration

Migrating the PAM Framework from Java 8 to OpenJDK 11.

Upgrading to the latest version of PAM provides you with enhanced security, improved performance, and access to all the newest features and enhancements we offer. To fully benefit from these improvements and ensure optimal compatibility, we encourage you to update your Java environment to at least the minimum supported version.

PAM now utilizes third-party libraries that are built on Java 9 or above. Without upgrading to OpenJDK 11, these new dependencies won't be properly supported. Upgrading PAM without updating your Java version can lead to system instability and negatively impact your experience. To ensure seamless functionality and avoid any disruptions, it's important to prioritize these changes.

If you want to migrate from PAM’s default Java 8 deployment to OpenJDK 11 or to the latest Java 8 build, please read the following article.

Prerequisites

  • An operational PAM deployment with the latest version. Please update to the latest available version before proceeding.

Considerations

  • Each PAM node that is updated will be offline and inaccessible for the entirety of the migration.
  • The user performing the migration will be required to update files and configurations on the PAM host server. Administrative privileges are required.
  • We highly recommend deploying a test instance of PAM that mirrors your production instance as closely as possible to test the migration (DB type, Federated Sign-In, certificates, MFA/SSO, AD Integration, etc). Once the migration is successful with the test instance you can reproduce the procedure on your production instance.

Please read the entire procedure outlined in the article before beginning. If you have any questions, please contact our Support team: https://support.imprivata.com/.

Step 1. Download Migration Components

Step 2. Stop the PAM Services

Step 3. JRE to OpenJDK Migration

Step 4. Start the PAM Services

Step 5. Test and Verify

Rollback

Step 6. Cleanup

Step 1. Download Migration Components

  1. Download the latest version of the OpenJDK 11 archive using the AdoptOpenJDK link below to your PAM host server (Windows or Linux) and extract the archive to your $PAM_HOME directory. The extracted archive will create a new directory with a name resembling $PAM_HOME/jdk-11.x.x.

  2. Download the OpenJDK 11 compatible PAM Federated Sign-in Module from the below location. Once downloaded, extract this zip to a temporary location on the PAM host server. Do not extract this archive to $PAM_HOME. Please note that if you are not using the Federated Sign-in Module, then you can skip this step.

  3. Download the PAM JDK Update Pack to your PAM host server (Windows and Linux) and extract the archive to your $PAM_HOME directory. The extracted archive will create a new directory with the name $PAM_HOME/pam-jdk11-pack.

Step 2. Stop the PAM Services

Once the services are stopped, PAM will become inaccessible until the entire migration is completed.

  1. For Windows deployments, stop the PamManagement and PamDirectory services:
    2. Copy 
    net stop PamManagement
    Copy 
    net stop PamDirectory

  2. For Linux deployments, stop the pammanager and pamdirectory services:

    Copy 
    service pammanager stop
    Copy 
    service pamdirectory stop

Step 3. JRE to OpenJDK Migration

  1. Replace the existing PAM jre directory.

    • Rename $PAM_HOME/jre to $PAM_HOME/jre.8

    • Rename $PAM_HOME/jdk-11.x.x to $PAM_HOME/jre

  2. Copy JRE 8 Certificates and Configurations:

    • Copy the file $PAM_HOME/jre.8/lib/security/cacerts to $PAM_HOME/jre/lib/security overwriting the current file.

    3. Note: This step will migrate the existing certificates loaded into the previous PAM deployment including ADS, AD connection certificates as well as SSL certificate for CAS integration.

  3. Update PAM container files.

    • Copy all files from $PAM_HOME/pam-jdk11-pack/bin to $PAM_HOME/bin overwriting the current files.

    • (Linux only) Copy all files from $PAM_HOME/pam-jdk11-pack/web/bin to $PAM_HOME/web/bin

    Note: This step resolves two issues with the compatibility between Java versions: deprecated endorsed folder and endpoint identity verification for LDAPS integrations.

  4. (Windows only) Redeploy Service:

    • From an administrative command prompt, navigate to $PAM_HOME and run the command:

      Copy 
      bin\ServiceManagement.cmd remove

    • When the above command completes successfully, run the command:

      Copy 
      bin\ServiceManagement.cmd install

      Note: The PamManagement service resets to the default Local System account Log on property once this service for PAM is reinstalled. If you are using a Log account other than an Local System account for this service then you must restore it prior to restarting the PamManagement service. Navigate to Services on Windows and find PamManagement, right-click and select Properties. Go to the Log on tab, select This account: and restore the required service account.

      PamManagement-Property.png

  5. Redeploy the Federated Sign-In Module. If you are not using the Federated Sign-in Module, you can skip this step.

    • Move $PAM_HOME/web/webapps/cas to $PAM_HOME

    • Move $PAM_HOME/web/webapps/cas.war to $PAM_HOME

    • Copy the downloaded cas.war from step (1b) to $PAM_HOME/web/webapps

    Note: If you made any customizations to the Federated Sign-in Module, they may be lost and need to be redone after the migration is complete.

  6. Update External Database Dependencies. If you are using the Internal PAM database, then this step can be skipped.

    • Navigate to $PAM_HOME/web/webapps/xtam/WEB-INF/lib

    • Select and copy all the files that start with jaxb- and are of extension .jar (i.e. jaxb-*.jar) to $PAM_HOME/web/lib

Step 4. Start the PAM Services

  1. For Windows deployments, start the PamManagement and PamDirectory services:
    • Copy
      net start PamManagement
    • Copy
      net start PamDirectory

  2. For Linux deployments, start the pammanager and pamdirectory services:

      Copy 
      service pammanager start
      Copy 
      service pamdirectory start

Step 5. Test and Verify

Once the services come back online, you should now login and thoroughly test the system. This should include, but not be limited to:

  • Login with all applicable types of user accounts; Local, AD/LDAP, MFA and SSO.
  • Accessing existing records (and creating new records) in both the Record List and Personal Vault, including the unlock action.
  • Creating remote sessions.
  • Executing jobs and tasks (on demand and scheduled).
  • Viewing and exporting reports.

To confirm the migration, open the file $PAM_HOME/web/logs/catalina.currentDate.log and search for JVM Version:.

The displayed version should be 11.0.2+9 or the latest version that was downloaded.

Rollback

If the migration or testing fails and you need to rollback to the previous Java 8 framework, then follow this procedure. If you do not need to rollback, proceed to the next section.

  1. Stop the PAM services as described earlier
  2. Rename the new $PAM_HOME/jre to $PAM_HOME/jre.11
  3. Rename the previous $PAM_HOME/jre.8 back to $PAM_HOME/jre
  4. Delete the new $PAM_HOME/web/webapps/cas
  5. Delete the new $PAM_HOME/web/webapps/cas.war
  6. Move the previous $PAM_HOME/cas back to $PAM_HOME/web/webapps/cas
  7. Move the previous $PAM_HOME/web/webapps/cas.war back to $PAM_HOME/web/webapps/cas.war
  8. Start the PAM services as described earlier.

When the services come back online, PAM should be using the previous framework.

You should now perform the testing and validation again.

Step 6. Cleanup

After all the testing is complete and the system is fully operational, you may remove the following directories:

  • $PAM_HOME/jre.8
  • $PAM_HOME/pam-jdk11-pack
  • $PAM_HOME/cas
  • $PAM_HOME/cas.war