PingFederate Server

Configuration archive

On the System > Server > Configuration Archive window, you can export and import configuration archives as backup files for the current PingFederate installation.

In addition to backup, you can use configuration archives for disaster recovery purposes.

If the console server is still functional, you can import a recent configuration archive to solve the problem.

Using a configuration archive isn’t necessary in a clustered environment where the console server is still functional and some engine nodes are gone. In this case, create new engine nodes and then replicate the configuration from the console node.

If the console server and the engine nodes are all gone, you can import a recent configuration archive to a new console server and then replicate the configuration to new engine nodes. All other configurations that occurred outside the archive will have to be redone manually.

If changes were made to the configuration since the last backup archive was created, the next time an administrator signs on to the administrative console or imports an existing archive, PingFederate automatically creates a time-stamped configuration (.zip) archive. The archives are stored in the <pf_install>/pingfederate/server/default/data/archive directory.

The automatic backup process typically completes without delays. For deployments with hundreds of connections or OAuth clients, or both, administrators can configure PingFederate to create configuration archives periodically instead. Learn more in Configuring a backup schedule.

Additionally, administrators can export the current configuration to a .zip file in the Configuration Archive window. This window is only available to administrators whose accounts have been assigned the User Admin, Admin, Crypto Admin, and Expression Admin roles. Learn more in Administrative accounts.

The backup file contains your complete PingFederate configuration. To protect your data, confirm the backup file is protected with appropriate security controls in place before exporting it.

Sharing the archive is a security risk because the private keys are stored in the archive. An archive should only be shared if the security of that PingFederate instance is not important, such as a development or test environment.

You can import an existing archive for immediate deployment into a running PingFederate server.

You can also deploy a configuration archive manually by copying the .zip file to the environment,<pf_install>/pingfederate/server/default/data/drop-in-deployer directory. After copying the .zip file, it must be renamed to data.zip.

If you use the drop-in deployment process:

  • PingFederate won’t let you import the configuration archive of an older or newer version, and to ensure successful importation of the configuration archive file with this process, you must rename the file data.zip.

  • On startup, the heartbeat endpoint won’t return 200 until the archive import completes. If you have configured a health check or probe that can trigger a restart of the server, crash loop behavior can result. Review the configuration of these checks to ensure time thresholds are set appropriately.

Configuration archives are intended for admin console configuration only. The following files aren’t included in the archives:

  • Launch scripts in the <pf_install>/pingfederate/bin and <pf_install>/pingfederate/sbin directories.

  • Web container configuration files in the <pf_install>/pingfederate/etc directory.

  • Log files in the <pf_install>/pingfederate/log directory.

  • Database drivers and program files from adapters and any other plugins in the <pf_install>/pingfederate/server/default/lib and <pf_install>/pingfederate/server/default/deploy directories.

  • Other files, including the license file, the advanced cluster configuration files, and the user-facing email and HTML templates, in the <pf_install>/pingfederate/server/default/conf directory.

If any changes have been made to files that aren’t part of the configuration archive, those files must be preserved manually.

You can export a configuration archive, extract the .zip file, and determine whether specific files are part of the configuration archive, or not.

Draft connections in archives aren’t imported. Complete any unfinished partner connections if you want to include them in a full backup archive or in an archive to be used for configuration migration.