Without modification, PingCentral is secure by default:

  • The server certificate chain must be ultimately signed by one of the public certificate authority root certificates present in the JVM default trust store.
  • Hostname verification is performed. The hostname or IP address specified in the URL must match a name defined in the server certificate presented, which encompasses the distinguished name, subject alternative names, and wildcard matching.

If you want to use self-signed server certificates, root certificates, intermediate certificates, and certificates from a private certificate authorities, create a PingCentral-specific truststore and configure PingCentral to access it.

Each time a connection is made, PingCentral checks the remote server's certificate against the PingCentral-specific truststore. If certificate validation fails, PingCentral delegates validation to the default system truststore. If you disable delegation to the default truststore, the only trusted certificates are those in the PingCentral-specific truststore.

In PingCentral, two types of outbound connections perform server certificate validation using the PingCentral-specific truststore. You cannot configure these connections independently.

  • Admin API access to PingFederate to manage environments and deploy applications.
  • Back-channel access to the configured OIDC provider when SSO is enabled.

You can configure PingCentral so that hostname verification and certificate validation is disabled. However, it is highly recommended that these options only be disabled for demonstration or testing purposes.

PingCentral only reads truststore configurations at startup, so restart PingCentral after creating or configuring truststore information.

  1. To create a PingCentral-specific truststore:
    1. Run the following Java built-in keytool command.
      <JAVA_HOME>/bin/keytool -import -trustcacerts -alias <ALIAS> -file <PATH_TO_TRUSTED_AUTHORITY_CERT> -keystore <TRUST_STORE_FILE_NAME>.jks 
      Note:

      It is highly recommended that you store the new truststore in a secure location on the local file system of the PingCentral user, and limit access permissions to that user.

    2. Run this command for each certificate you need to import. Specify a unique alias for each certificate and ensure you refer to the same truststore file name each time you run this command.
    3. During this process, the system will prompt you to create a password to secure the truststore. You will need to provide this password when you configure PingCentral to access the truststore.
    4. To view a list of the certificates included in the truststore, run the following command:
      <JAVA_HOME>/bin/keytool -list -v -keystore <TRUST_STORE_FILE_NAME>.jks
      Note:

      Java trusts certificates in the configured truststore even if they are expired.

  2. To configure PingCentral to access the PingCentral-specific truststore:
    1. Open <PingCentral intallation directory>/conf/application.properties in a text editor and configure PingCentral to access the PingCentral-specific truststore.
    2. Locate the following properties, uncomment them by removing the # from the line, and define each property with your system-specific information:
    • server.ssl.trust-store=<ABSOLUTE_PATH_TO_TRUSTSTORE_JKS_FILE>
      Note:

      If the .jks file is in the PingCentral home/install directory, you can use a relative link instead: ${pingcentral.home}/<PATH_TO_TRUSTSTORE_JKS_FILE>

    • server.ssl.trust-store-password=<TRUSTSTORE_PASSWORD>

      On startup, PingCentral will attempt to access the truststore with the password specified here, which must be the password used when the truststore was created.

      Note:

      It is highly recommended that you secure the password using the obfuscation script available in bin/obfuscate, and by using output ciphertext rather than the cleartext secret.

  3. Configure the following PingCentral properties, as appropriate:

    • To force PingCentral to use the PingCentral-specific truststore as the certificate validation authority and not delegate validation to the default system truststore, uncomment the following property and set the value to false: server.ssl.delegate-to-system=false
    • To configure PingCentral so that it will accept a valid certificate even if the URL hostname does not match the one defined in the certificate, uncomment the following property and set the value to false: server.ssl.https.verify-hostname=false
    • To configure PingCentral so that certificate validation is completely disabled (any certificate presented by a server is trusted), uncomment the following property and set the value to true: server.ssl.trust-any=true