PingFederate Server

Using the migration tool

The migration tool, configcopy, can be used in conjunction with one or more property files to define the operational command and other parameters, including the source and target PingFederate servers, and to modify configuration settings as needed for the target environment.

About this task

As of PingFederate 10.2, the configcopy tool has been deprecated and will be removed in a future release.

Property-file templates are available for each command option in the <pf_install>/pingfederate/bin/configcopy_templates directory.

See the README.txt file in the configcopy_templates directory for a list of all commands and summary information. See the template files for parameters associated with each command or with use cases, as well as lists of Override Properties, which are configuration settings that can be modified in transit, where applicable.

Copies of the templates can be configured as needed and then used together, or combined into one file. Use the applicable file names as an argument when running configcopy.bat or configcopy.sh, depending on your operating system, for particular configurations, using the following command syntax.

(On Windows)

configcopy.bat -Dconfigcopy.conf.file=<properties_file1>; <properties_file2>;...

When paths are included with the file names, you cannot use backslashes (\). Use forward slashes (/) or escape the backslash (\\).

(On Linux)

configcopy.sh -Dconfigcopy.conf.file=<properties_file1>:<properties_file2>:...

The file separators are platform specific, corresponding to the syntax used for system-level path separators.

Also, you can specify any property values through command-execution arguments, using the following syntax

configcopy[.sh] -D<property>=<value> ...

where <property> is any property named in the properties file and <value> is the value. Command-line property designations take precedence over any values set in the properties file.

Access to the Connection Management Service is password-protected. The usernames and passwords might be set in the properties file for both the source and target web services, and passwords can be obfuscated. If passwords are set in the properties file, they cannot be overridden using the command line. If a password is not set, the configcopy tool prompts for it. Usernames must always be supplied where applicable, either in the command line or in the properties file.

The configcopy utility generates its own log file, configcopy.log, located in the <pf_install>/pingfederate/log directory. You can control settings for this log, as needed, in the file configcopy.log4j2.xml, located in the bin directory.

Importing connections or other discrete configurations at the target server is not subject to the same rigorous data validation performed by the administrative console during manual configuration. Although some checks are made, it is possible to create invalid connections using the connection-migration process. Therefore, you should not use the configcopy tool to create settings at the target that do not exist at the source. For connections and other configurations copied separately, the tool is designed only for modifying the values of existing source settings to make them applicable to the target environment.

To avoid errors and prevent unstable target configurations due to missing components or faulty cross-component references, such as invalid ID references from connection configurations to datastore configurations, adhere closely to the instructions provided in the following procedure.

Steps

  1. Enable access to the Connection Management Service for both the source and target PingFederate servers. For more information, see Configuring service authentication.

  2. Determine which component configurations need to be copied, including plugins.

    For example, connection configurations always reference either adapter or token-translator configurations, or both, and may reference datastore configurations. These are all separate configurations, and must be copied separately in conjunction with copying connection configurations, unless they already exist at the target.

    Server Settings, unless pre-configured at the target, also need to be copied over separately.

    Provisioning settings can be copied separately to update target connections, as needed.

  1. Determine whether any configuration property files or other supporting files need to be copied.

  2. Ensure necessary plugin JAR files are installed on the target server.

    The configcopy tool does not copy over these files, which include libraries for adapters, token translators, and JDBC or any custom database drivers.

    The JAR files are located in either <pf_install>/pingfederate/server/default/deploy or <pf_install>/pingfederate/server/default/lib.

  3. On the target server, ensure that signing certificates, or certificates used for XML decryption, are already in place. For more information, see Certificate and key management.

    Private keys are not copied from server to server, public certificates can be copied. However, you can use configcopy to upload keys and certificates to the target server.

    Look for identifying information about the target keys so you can reference the certificates in connection-copy properties.

  4. If you have not yet installed your organization’s CA-issued SSL server certificate on both the target and source servers, you can do so with a configcopy command. Otherwise, use one of the following methods to ensure that configcopy can contact both servers:

    • (Recommended) Install the Issuer certificate for the PingFederate SSL certificate in a separately managed trust store. Then the location of the file can be specified when running configcopy using the property configcopy.connection.trust.keystore.

    • Install the Issuer certificate for the PingFederate SSL certificate into the trust store for the Java runtime where configcopy runs.

      If different SSL certificates are installed on the two servers, the configcopy tool must be able to trust both. In this case, both certificates must be installed in the trust store used by configcopy, or in the trust store for the Java runtime where configcopy runs.

  5. Create properties files for the necessary commands, and for associated command-parameter values needed to copy the required configurations and any additional files.

    See the README.txt file and to the properties-file templates in the <pf_install>/pingfederate/bin/configcopy_templates directory.

    This step and those following assume the use of properties files based on the templates provided. You can also use command-line parameters. For more information, see previous steps in this section.

  6. If you are copying connections, override ID properties referencing adapter, datastores or other plugin configurations, as needed see [reuseStep2].

    Ensure that the plugin configurations are either previously defined at the target or are part of the same configcopy process used to copy the connections that depend on them.

  7. Create a script or run a command, or command series, that executes configcopy for each of the prepared properties files.

    See the previous discussion for syntax requirements, or the README.txt file.