PingFederate Server

Configuration archive

You can use 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.

  • In a clustered PingFederate

Using a configuration archive is not necessary in a clustered environment where the console server is still functional and some of the engine nodes are gone. In this case, create new engine nodes and then replicate the configuration from the console node. environment, 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 of 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.

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.

The Expression Admin role must be assigned to give administrators sufficient permissions to create configuration archives.

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.

On the Configuration Archive window, administrators can import an existing archive for immediate deployment into a running PingFederate server.

Administrators 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 will not 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 will not 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 administrative-console configuration only. The following files are not 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 are not 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 are not 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.