PingFederate Server

Upgrade considerations introduced in PingFederate 8.x

InterReqStateMgmtMapImpl.expiry.mins renamed

The InterReqStateMgmtMapImpl.expiry.mins setting in the size-limits.conf file has been renamed in PingFederate 8.4.2. If you have previously modified the value of this setting, please refer to Copying customized files or settings for more information.

An improved index (IDX_FIELD_NAME) in the database table for OAuth clients

PingFederate 8.4 has modified an existing index (IDX_FIELD_NAME) in the pingfederate_oauth_clients_ext database table as a general improvement. For information about modifying this index in your existing table, see Reviewing database changes.

Security enhancement to the OAuth token endpoint

Starting with version 8.3, a new PingFederate installation no longer allows OAuth clients to send access token validation requests to its token endpoint (/as/token.oauth2) by the HTTP GET method.For upgrades, the Upgrade Utility applies this new behavior to the new installation as well unless the <pf_install>/pingfederate/server/default/data/config-store/oauth-token-endpoint-binding.xml file has been modified in the older version, in which case the Upgrade Utility preserves the modified configuration.

SSLv2Hello disabled

Starting with PingFederate 8.3, SSLv2Hello is disabled. Customers are encouraged to update their applications to use TLSv1, TLSv1.1, or TLSv1.2 when establishing HTTPS connections with PingFederate.As needed, SSLv2Hello can be re-enabled as needed. See Enabling SSLv2Hello for more information.

License management simplification

Starting with version 8.2, PingFederate no longer maintains its license information in the <pf_install>/pingfederate/server/default/data/.pingfederate.lic file, which is known as the secondary license file in the previous versions of PingFederate. The .pingfederate.lic, if any, is ignored.

We recommend using the administrative console to simplify the license management aspect of a standalone PingFederate server or a clustered PingFederate environment.

Security enhancement for a clustered PingFederate environment

As of PingFederate 8.1, when encryption is enabled for the network traffic sent between nodes in a clustered PingFederate environment, you must provide an authentication password for the cluster as well; otherwise PingFederate aborts during its startup process.For more information about the pf.cluster.encrypt and pf.cluster.auth.pwd properties, see Deploying cluster servers.

Metadata signing

Previously, when no signing certificate was chosen on the Metadata Signing tab on the System → Protocol Metadata → Metadata Settings window, the /pf/sts_mex.ping and /pf/federation_metadata.ping system-services endpoints provided signed WS-Trust and WS-Federation metadata using one of the certificates configured on the Security → Certificate & Key Management → Signing & Decryption Keys & Certificates window.Starting with PingFederate 8.1, if no certificate is selected in the Metadata Signing menu, PingFederate provides unsigned metadata at both aforementioned endpoints. Select a certificate in the Metadata Signing window if signed metadata is desired.

Hostname verification for email server

For email notification using SSL or TLS, hostname verification of the certificate is available starting with PingFederate 8.1. This option is enabled automatically when the Use SSL or Use TLS check box is selected for a new configuration. When upgrading from a previous version of PingFederate, if email notification had already been configured to use SSL or TLS, the Upgrade Utility preserves the configuration without activating the hostname verification option for compatibility reasons. Administrators should consider activating this new option to improve security.

New login template file for the HTML Form Adapter

Previously, when multiple instances of the HTML Form Adapter are chained together (for example, in an instance of the Composite Adapter), the subsequent instance tried authenticating the end user with the credentials from the previous login, which might fail when the HTML Form Adapter instances were configured to use different password credential validators (PCVs). Although this use case is rare, PingFederate 8.1 has corrected the behavior. As a result, the login template file, <pf_install>/pingfederate/server/default/conf/template/html.form.login.template.html, has been modified.If you have previously customized this login template file and if you have authentication use cases that chain multiple instances of the HTML Form Adapter, you should re-customize using the new html.form.login.template.html file.

New connection pool library

As of PingFederate 8.0, support for BoneCP as the JDBC connection pool library has been deprecated and replaced with Apache Commons DBCP 2, which requires JDBC 4.1 or later drivers.Verify the database-driver JAR files, found in the <pf_install>/pingfederate/server/default/lib directory, meet the minimum version requirement. If you are using JDBC drivers of version 4.0 (or earlier), contact your vendors for the latest drivers and replace the older JDBC database-driver JAR files with the latest.For more information, including re-enabling BoneCP as the JDBC connection pool library, see Reviewing database changes.

Log4j 2 upgrade

PingFederate 8.0 has upgraded its logging framework from Log4j to Log4j 2.If you have previously customized <pf_install>/pingfederate/server/default/conf/log4j.xml, you will need to manually migrate your changes to the new log4j2.xml in the same conf directory. See Logging configurations for instructions.

include:::partial$pf_rc_notes.adoc[tags=pf_ph_testedJdbcDriver]To obtain the database driver .jar file, contact your database vendor. Install the database driver file to the <pf_install>/pingfederate/server/default/lib directory, and then restart the server.