PingFederate Server

Upgrade considerations

The following modifications since PingFederate 12.0 might affect existing deployments.

Refresh token MySQL deadlocks

We’ve fixed a defect that caused multiple refresh token requests in short succession to result in Java database connectivity (JDBC) data source deadlocks and duplicated data entry into the database. The fix can cause significant performance issues if PingFederate or the JDBC data source have insufficient resources.

HTTP request logging

Starting with PingFederate 12.3, HTTP requests to the runtime engine and admin console are no longer logged to request.log and request2.log files.

HTTP requests are now logged to the runtime-request.log and admin-request.log files. Like other PingFederate log files, you can configure the output to these files using the log4j2.xml and run.properties files.

You can revert to the legacy logging behavior using useLog4j2Logger and format strings.

Learn more in HTTP request logging.

Resource indicators for OAuth 2.0

Starting with PingFederate 12.1, we’ve added support for the resource parameter to allow clients to indicate the protected resources to which the client is requesting access.

If the incoming authorization or token request includes resource parameter(s), then you must add the resource(s) to the Resource URIs within an Access Token Manager. Otherwise, the authorization or token request will result in an error.

Learn more in Managing resource URIs.

Persist users consent decision when revoking refresh_token

Starting with PingFederate 12.0, you can configure your authorization server settings for OAuth and OpenID Connect (OIDC) users so that their decisions to grant access can be persisted after a refresh_token is revoked.

If you have a custom implementation of the AccessGrantManager interface, you need to add the new methods:

  • Required: void updateExpiry(AccessGrant accessGrant)

  • Optional:

    Collection<AccessGrant>
getByUserKeyClientIdGrantType(String userKey, String clientId, String grantType)

    If you don’t implement these changes, PingFederate will use existing methods in the AccessGrantManager interface to perform the same lookup with additional filtering.

    When you enable this feature, PingFederate creates more records in the external datastore used for Access Grants. It will not necessarily generate more data because OAuth consent records don’t retain the same information as access grants.

    You must manually add the newly-added index to your existing Access Grant external datastore.

    JDBC (for all supported JDBC types)

    Create a new index UNIQUEUSERIDCLIENTIDGRANTTYPEIDX.

    You can find the create index command in the table-setup scripts for your database server provided in the <pf_install>/pingfederate/server/default/conf/access-grant/sql-scripts directory.

    LDAP

    For PingDirectory, create a new index accessGrantGrantType and rebuild your index.
Alert and report when approaching maxThreads

Starting with PingFederate 12.0, you can configure your runtime notifications to alert you when the number of threads in use exceeds a set threshold. You can also use this feature to initiate and log a thread dump event that you can use for troubleshooting.

If you’re using a customized log4j.xml file, add the following to your list of Appenders:

<!-- Thread Pool Exhaustion thread dump log : A size based file rolling appender -->
<RollingFile name="ThreadDumpAppender"
             fileName="${sys:pf.log.dir}/thread-pool-exhaustion-dump.log"
             filePattern="${sys:pf.log.dir}/thread-pool-exhaustion-dump.log.%i"
             ignoreExceptions="false">
    <PatternLayout>
        <!-- Uncomment this if you want to use UTF-8 encoding instead
            of system's default encoding.
        <charset>UTF-8</charset> -->
        <pattern>%d %m%n</pattern>
    </PatternLayout>
    <Policies>
      <SizeBasedTriggeringPolicy
                size="10000 KB" />
    </Policies>
    <DefaultRolloverStrategy max="5" />
</RollingFile>

Also add the following to your list of Loggers:

<AsyncLogger name="ThreadDumpLogger" level="INFO" additivity="false" includeLocation="false">
    <appender-ref ref="ThreadDumpAppender" />
</AsyncLogger>
PingID properties file encrypted

From RADIUS PCV 3.0.4 and later, the PingID properties file is encrypted after it is uploaded to PingFederate.

If you are upgrading from an earlier version, to ensure the properties file is encrypted, you need to upload it to the PingID RADIUS PCV instance in PingFederate.
Skip redirect to authentication application if no action is required

Starting with PingFederate 12.0, API-capable IdP adapters can now prevent a redirect to the authentication application if no user interaction is required.

If the adapter determines that no authentication action is required—for example when a request parameter is being passed, or because the adapter maintains a valid session—PingFederate will skip the redirect to the authentication application.

This capability is implemented in the HTML Form Adapter and the Identifier First Adapter, and is also available for custom adapters using the TRY_LOOKUP_AUTHN metadata key and input parameter.

Prevent JGroups thread pool exhaustion in large clusters

Starting with PingFederate 12.0 the default value of pf.cluster.TCPPING.return_entire_cache in jgroups.properties to false on fresh installations of PingFederate.

Setting pf.cluster.TCPPING.return_entire_cache to false avoids an issue where the thread pool for cluster RPCs temporarily runs out of threads and some RPCs get dropped. This issue only occurs in large clusters under heavy load.

Setting pf.cluster.TCPPING.return_entire_cache means that all clusters must be listed in pf.cluster.tcp.discovery.initial.hosts.

On upgrade, the existing value of pf.cluster.TCPPING.return_entire_cache is preserved, but customers using TCPPING with large clusters should set it to false, provided that all cluster members are listed in pf.cluster.tcp.discovery.initial.hosts.

Removed support for Java 8

Starting with version 12.0, PingFederate no longer supports Java 8. Use Java 11, Java 17, or Java 21 instead.

Learn more in Java environment.

Hostname characters

If you’re using PingFederate on Java 17 or 21, your hostname can’t include underscores. Only ASCII letters, digits, and hyphens are permitted.

Learn more in RFC 3490.

Categories for verbose log settings

Starting with PingFederate 12.0, some information has been moved from the Core log category to the new Protocol Requests and Responses log category. Learn more in Log settings.

Properties in start.ini moved to run.properties

Starting with PingFederate 12.0, the properties previously in the start.ini file are now in the run.properties file to facilitate future upgrade of those properties.

Default port range in tcp.xml

Starting with PingFederate 12.0, the default port range in the tcp.xml file has been changed from 10 to 0.

As a result, PingFederate will only listen on the configured pf.cluster.bind.port and will fail to start up if that port is in use.

OpenID Connect Front-Channel Logout

Starting with version 12.0, PingFederate supports OpenID Connect Front-Channel Logout. For this feature to work correctly, if the value for the exclude-patterns item in the X-Frame-Options map in <pf_install>/pingfederate/server/default/data/config-store/response-header-runtime-config.xml has been edited, then you must add /fc-logout.openid;/resume/sp/fc-logout.ping to the exclude-patterns item.

SAML IdP Discovery and SAML AP Affiliations

As of PingFederate 12.0, the SAML IdP Discovery and SAML AP Affiliations features have been deprecated, and will be removed in a future release.

Text Message SSPR

Starting with PingFederate 12.0, text message self-service password reset (SSPR) has been removed.

SAML SP connection configuration

Existing SAML SP connections that rely on multiple session states in a single transaction will be affected by new session state validation measures introduced in PingFederate 11.2.5 and 11.3 under PF-33168. Learn more in PingFederate 11.3 (June 2023).

You can find more information about how to diagnose and resolve issues caused by this update in Solicited SAML Response Validation in the Ping Identity Support Portal.

Upgrade from PingFederate 6.x and 7.x

Starting with version 12.0, PingFederate no longer supports upgrading from PingFederate 6.x or 7.x.