--- title: Upgrade considerations introduced in PingFederate 12.x description: The following modifications since PingFederate 12.0 might affect existing deployments. component: pingfederate version: 13.1 page_id: pingfederate:upgrading_pingfederate:pf_upgrade_considerations_12x canonical_url: https://docs.pingidentity.com/pingfederate/13.1/upgrading_pingfederate/pf_upgrade_considerations_12x.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: July 10, 2024 --- # Upgrade considerations introduced in PingFederate 12.x The following modifications since PingFederate 12.0 might affect existing deployments. * OAuth **Resource URIs** must be defined Starting with PingFederate 12.1, reusing a previous version's OAuth authentication calls that contain **Resource URIs** will fail if the required **Resource URIs** aren't defined in the **Access Token Manager**. Learn more in [Managing resource URIs](../administrators_reference_guide/help_beareraccesstokenmgmtplugintasklet_atmselectionsettingsstate.html). * `pf.admin.baseurl` must be set A defect fix requires the `pf.admin.baseurl` property to be explicitly set in `run.properties`. This prevents admin console URL redirects from failing when PingFederate is accessed through a load balancer with a port that differs from `pf.admin.https.port`. * 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) *(tooltip: \
\

A Java API that allows Java programs to interact with databases.\

\
)* 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](../administrators_reference_guide/pf_http_request_loggin.html). * 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](../administrators_reference_guide/help_beareraccesstokenmgmtplugintasklet_atmselectionsettingsstate.html). * 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) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* 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 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 `/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: ``` %d %m%n ``` Also add the following to your list of Loggers: ``` ``` * 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](../administrators_reference_guide/pf_html_form_adapt.html) and the [Identifier First Adapter](../administrators_reference_guide/pf_identifier_first_adapter.html), 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](../installing_and_uninstalling_pingfederate/pf_system_requirements.html#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](https://www.rfc-editor.org/rfc/rfc3490.html). * 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](../administrators_reference_guide/help_logsettingstasklet_logsettingsstate.html). * 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 `/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)](../release_notes/pf_release_notes_113.html). You can find more information about how to diagnose and resolve issues caused by this update in [Solicited SAML Response Validation](https://support.pingidentity.com/s/article/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.