PingFederate Server

Upgrade FAQ

Planning your upgrade

I want to upgrade PingFederate. What resources can help with this?

The following links contain helpful resources to plan your PingFederate upgrade:

Use the version selector on the upper left of the page to select the documentation for the target version of PingFederate.
I’m upgrading from a legacy version of PingFederate, how do I start?

If you’re running PingFederate 8.4 or older, you should upgrade to version 8.4 first. After you’ve upgraded and tested your 8.4 deployment, you can upgrade to a later version.

PingFederate versions 7.x and earlier can’t upgrade directly to PingFederate 12.x. You must perform an incremental upgrade.
How can I upgrade PingFederate with the least amount of downtime?

PingFederate doesn’t support a fully zero downtime upgrade, but you can perform a near-zero downtime upgrade.

Downloads

I want to upgrade to a specific release that’s no longer available on the Ping Identity downloads page. How can I download the version I need?

Submit a support case to request the release you need, and we’ll provide you with a link.

Do I need to download the Upgrade Utility separately?

All supported releases include the Upgrade Utility in the PingFederate package, so there’s no need to download it separately.

Releases prior to 10.x don’t include the Upgrade Utility, so you must download that separately.

For example, if you want to upgrade to 8.4, you need to download the PingFederate 8.4 package and the PingFederate 8.4 Upgrade Utility package.

Performing the upgrade

How do I perform a major version or minor version upgrade?

You can upgrade to the next major or minor version using the PingFederate Upgrade Utility or the Windows installer. The Upgrade Utility is generally the preferred method.

How do I perform a maintenance release upgrade?

If you’re upgrading to a maintenance release for PingFederate 10.x or later, you can upgrade by deploying the in-place maintenance update package. You can also use the PingFederate Upgrade Utility or the Windows installer.

Can I use the Windows MSI Installer to upgrade?

Yes, but only if PingFederate was intially installed using this method. If it wasn’t, or if you’re unsure how PingFederate was installed, use Upgrade Utility.

Do I have to use the Upgrade Utility to upgrade to major or minor releases in a DevOps environment?

Yes. In a DevOps environment, you must always use the Upgrade Utility. Learn more in the DevOps upgrade guide.

Can I use a configuration archive or bulk import from a previous release into a newer release?

PingFederate 12.1 and earlier: No. The Upgrade Utility or Windows installer are the only supported upgrade methods for major or minor releases. The Upgrade Utility is generally the preferred method.

PingFederate 12.2 and later: A configuration archive from version 11.1 or later will be upgraded automatically when imported. Importing an archive from a version earlier than 11.1 won’t be upgraded or supported.

This method only imports data stored in the configuration archive, which excludes things like templates, .properties, or .conf file settings, and other settings that the Upgrade Utility would migrate. As such, we recommend this method only for environments with appropriate automation to merge these configurations post-upgrade.

Learn more in Upgrading configuration data.

Do I need to start my upgrade with the Admin Console?

Yes. The Admin Console is the only interface that inherits the configuration during the upgrade (such as adapter, connections, and datastores). Failing to upgrade and start the Admin Console and perform cluster replication results in upgraded engine nodes missing key configuration changes needed to process transactions.

Licensing

Do I need to upgrade my license when performing an upgrade?

Yes, if you’re upgrading to a new major release. You can upgrade your license by following this guide.

Does upgrading my license invalidate my existing license?

No. Your existing license continues to be valid until the expiration date.

General

How do I know if the version I am running or upgrading to is supported?

You can check the support status and end-of-life dates for PingFederate at the End of Life tracker.

Learn more in Ping Identity’s End of Life Policy.

Does PingFederate support a mixed-version cluster?

You can mix maintenance releases on a cluster but not major and minor releases.

  • PingFederate servers running 12.1.2 and 12.1.4 can exist within the same cluster. This makes it easier to upgrade to a new maintenance release. We recommend upgrading your older versions rather than keeping the mixed-version cluster long term.

  • PingFederate servers running 12.1 and 12.2 won’t communicate with each other.

  • PingFederate releases prior to 10.x don’t support any form of mixed-version clustering.

Do I need to update Java when I upgrade PingFederate?

Possibly. Check the system requirements for the target version to see whether your current JDK release is supported.

Does a PingFederate upgrade also upgrade my Adapters and Integration Kits?

By default, the Upgrade Utility migrates the existing Integration Kit versions from the source version. This is to maintain functionality. You can then upgrade to new Integration Kit versions after your PingFederate upgrade.

You can use the -c custom mode when running the Upgrade Utility. This prompts the administrator to choose to use the existing or new version of the integration, assuming the target PingFederate package includes the newer version of that integration.

Integration kits not included in the PingFederate package are always migrated from the source version.

Will my upgrade affect my existing use cases and functionality?

Possibly. Review the Upgrade considerations before upgrading, and perform the upgrade in a test environment so you can test your use cases before upgrading a production environment.

What happens to state and Authentication Sessions when upgrading?

When performing a major or minor version upgrade, state and sessions held in memory will be lost. Persistent Sessions are stored in an external database and will be available post-upgrade.

Issues and Rolling Back

After running the Upgrade Utility, when I start the Windows Service, the old PingFederate version starts up. Why?

The Upgrade Utility doesn’t upgrade the Windows Service.

  • You can uninstall the existing Windows Service and install the Windows Service for the new version.

  • Alternatively, you can install the new Windows Service with a unique name so that both services are available to start and stop as you need.

How can I roll back a PingFederate upgrade?

PingFederate upgrades using the Upgrade Utility are non-destructive, meaning the previous version remains intact alongside the newly upgraded release. As such, you can roll back the upgrade by stopping the new service and starting the old service.

If I roll back my upgrade, do I have to rerun the Upgrade Utility when we are ready to retry the upgrade?

If your environment has changed since the last upgrade, you should run the Upgrade Utility again to ensure these chages are carried over.

How can I get help if I encounter issues with the new version post-upgrade?

Submit a support case with a description of the problem, along with the server.log and upgrade.log files and any other relevant details.

If this is a production environment and the issue is causing a significant impact, you should roll back the upgrade to restore functionality while the case is investigated.

I attempted to upgrade using an unsupported method but encountered problems. What can I do?

If you attempted to upgrade using an unsupported method, like importing a configuration archive from an older version into a new version or from an incompatible version into 12.2 or later, you should start by rolling back to the previous version and upgrade using the Upgrade Utility.

Upgrading using unsupported methods frequently causes problems, which can be difficult to diagnose.

Ping Support can’t assist with problems caused by an unsupported upgrade process.

After upgrading, I get a warning banner in the PingFederate Admin Console regarding the HyperSQL Database (HSQLDB). What’s causing this?

This banner is expected if you use the unsupported HSQLDB in your environment. Learn more in Hypersonic database Usage with PingFederate.