PingFederate Server

Upgrade considerations

The following modifications since PingFederate 12.0 might affect existing deployments.

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 or Java 17 instead.

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.