--- title: Upgrade considerations introduced in PingFederate 11.x description: The following modifications since PingFederate 11.0 might affect existing deployments. component: pingfederate version: 12.3 page_id: pingfederate:upgrading_pingfederate:pf_upgrade_considerations_11x canonical_url: https://docs.pingidentity.com/pingfederate/13.1/upgrading_pingfederate/pf_upgrade_considerations_11x.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: September 16, 2026 superseded_by: https://docs.pingidentity.com/pingfederate/13.1/upgrading_pingfederate/pf_upgrade_considerations_11x.html --- # Upgrade considerations introduced in PingFederate 11.x The following modifications since PingFederate 11.0 might affect existing deployments. * `start.ini` configurations The parameters set in the `start.ini` file aren't upgraded automatically. You must update the configurations manually after upgrade. Beginning with PingFederate 12.0, the `start.ini` file is deprecated and its parameters are moved to the `run.properties` file. * Apache Velocity Engine upgrade With PingFederate 11.3, we've upgraded the Apache Velocity templating engine from version 1.6 to version 2.3. All out-of-the-box PingFederate HTML templates are backward compatible with this new version of Velocity, but customized templates might require edits to work with version 2.3. For a complete list of changes to the Velocity engine that might require updating customized templates, see [Upgrading](https://velocity.apache.org/engine/2.3/upgrading.html) in the Apache Velocity Engine documentation. * Replacement of `hivemodule.xml` Starting with PingFederate 11.3, the distribution ZIP file no longer contains the `hivemodule.xml` file. Instead, the distribution contains a new file: `service-points.conf` in the `/pingfederate/server/default/conf/` directory. On first startup, PingFederate processes `service-points.conf` and generates a default `hivemodule.xml`. The advantage of the `service-points.conf` file is that it lets you use environment variables to override hivemodule settings without having to modify an XML file. Learn more in [Overriding configuration settings using environment variables](../administrators_reference_guide/override_configuration_settings_using_environment_variables.html). When you upgrade a supported version of PingFederate older than 11.3 to version 11.3 or later, the `service-points.conf` file replaces the `hivemodule.xml` file in the `/pingfederate/server/default/conf/META-INF/` directory with a generated default `hivemodule.xml` file in `/pingfederate/server/default/conf/generated-hivemodule/META-INF/` directory. If you want to continue using `hivemodule.xml` instead of `service-points.conf`, add `hivemodule.xml` to the `/pingfederate/server/default/conf/META-INF/` directory after upgrading PingFederate. During startup, if PingFederate finds `hivemodule.xml` in that directory, it will ignore `service-points.conf`. Later, when you upgrade PingFederate 11.3 or newer, the `hivemodule.xml` file won't be replaced. These changes don't affect your upgrade process in either of the following cases: * You upgrade to PingFederate 11.3 or later using the upgrade utility, as recommended * You don't need to modify the default `hivemodule.xml` file | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you start a new instance of PingFederate 11.3 or later using a process that depends on having `hivemodule.xml` in the distribution ZIP file, the process will fail. To prevent this startup failure, do one of the following:- Launch a local instance of the new PingFederate version, which generates the default `hivemodule.xml` in `/pingfederate/server/default/conf/generated-hivemodule/META-INF/`. Copy and, if needed, modify `hivemodule.xml`. Use that file to launch your production PingFederate instance. When you launch PingFederate, your existing process can find `hivemodule.xml` and work as expected. - Disable your process that needs to work with `hivemodule.xml` directly. If needed, modify the `service-points.conf` file that comes with PingFederate 11.3 or later. When you launch PingFederate, it generates `hivemodule.xml` and works as expected. - Disable your process that needs to work with `hivemodule.xml` directly. If needed, configure the PingFederate environment variables. When you launch PingFederate, it uses those environment variables and generates `hivemodule.xml`. | * Configuration change necessary for MFA adapters As of PingFederate 10.2, when you define policies using multi-factor authentication (MFA) *(tooltip: \
\

An electronic authentication method where a user is granted access only after presenting two or more verification factors for authentication.\

\
)* adapters, you must select the **User ID Authenticated** checkbox in the **Incoming User ID** popup to allow users to register as a new MFA user. You should only select this checkbox if the previous authentication source has verified the **Incoming User ID**. You shouldn't select the checkbox if the MFA adapter is part of a policy used for password reset or password change. Learn more in [Defining authentication policies](../administrators_reference_guide/pf_defining_auth_policies.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Administrators using the PingID adapter must review existing policies and select this checkbox if appropriate. Otherwise, the adapter will prevent new user registration. | * LDAP properties Starting with PingFederate 11.3, the `/pingfederate/bin/ldap.properties` file includes the new `ldap.type` field. This mandatory field specifies the LDAP directory server type. If you use [LDAP for administrative console or administrative API authentication](../administrators_reference_guide/pf_enabling_ldap_auth.html), ensure you set this field to a valid value. * Refresh token rolling grace period When upgrading from PingFederate versions newer than 11.0.1, if the **Authorization Server Settings** page was never modified, PingFederate sets a default value of `0` for **Refresh Token Rolling Grace Period**. If the **Authorization Server Settings** page was modified, PingFederate retains the previously set value. Learn more in the Refresh Token Rolling Grace Period field in [Configuring authorization server settings](../administrators_reference_guide/help_authorizationserversettingstasklet_oauthauthorizationserversettingsstate.html). * Refresh token chain revocation PingFederate 11.3 introduced refresh token *(tooltip: \
\

A long-lived token used by OAuth clients to obtain a new access token without having to obtain fresh authorization from the resource owner.\

\
)* chain revocation, which revokes a chain of refresh tokens when a token in that chain is revoked or reused. This behavior is the default in new installs, but not in upgrades to 11.3 or newer. You can change the behavior using the `RevokeReplayedRefreshToken` setting in the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.AuthzServerManagerImpl.xml` file. Learn more in [refresh token reuse and revocation](../release_notes/pf_release_notes_113.html#refresh-token-reuse-and-revocation-best-practice). * Metadata response configuration Starting with PingFederate 11.2, PingFederate provides an OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* authorization server metadata endpoint, `/.well-known/oauth-authorization-server`. The new endpoint returns configuration information that OAuth clients need to interface with PingFederate using OAuth 2.0. You can customize what information the endpoint returns by editing the `/pingfederate/server/default/conf/openid-configuration.template.json` template file, which also determines what information the OpenID Connect metadata endpoint returns. If you previously modified `openid-configuration.template.json` for the OpenID Connect metadata endpoint, merge your modifications into the 11.2 version of the template. * Processing policy fragments Starting with PingFederate 11.2, PingFederate processes policy fragments independently from policies and other fragments. The nodes in a fragment are no longer aware of the exterior policy or fragment invoking it, other than the fragment input values that the input authentication policy contract provides. The inverse is also true. The exterior policy or fragment is no longer aware of the processing that occurred within an interior fragment, only what is mapped to the output authentication policy contract. * Integration with Amazon Web Services (AWS) CloudHSM Starting with PingFederate 11.2, PingFederate's integration with Amazon Web Services (AWS) *(tooltip: \
\

An Amazon subsidiary providing cloud computing platforms.\

\
)* CloudHSM now requires the AWS CloudHSM Java Cryptography Extension (JCE) provider for Client SDK 5. There are a number of new limitations around assertion and token decryption with Client SDK 5. Learn more about the limitations in the hardware security module (HSM) *(tooltip: \
\

A dedicated cryptographic processor designed to manage and protect digital keys. HSMs act as trust anchors that protect the cryptographic key lifecycle by securely managing, processing, and storing cryptographic keys inside a hardened, tamper-resistant device.\

\
)* issue section of the [Release Notes](../release_notes/pf_release_notes.html). In addition, the `java.security` file in the Java Runtime Environment (JRE) *(tooltip: \
\

A software layer that provides the class libraries and resources needed for a Java program to run.\

\
)* no longer needs to be modified and client files do not need to be copied to the `JAVA_HOME/jre/lib/ext` directory. Learn more about how to upgrade the HSM client in the updated setup instructions in [Integrating with AWS CloudHSM](../getting_started_with_pingfederate/pf_integra_aws_cloudhsm.html). * Verbose logging Starting with PingFederate 11.2, you can enable verbose logging with the **Log Settings** page or with the administrative API on nodes that have the updated version of the `/pingfederate/server/default/conf/log4j2.xml` file. If `log4j2.xml` was previously modified, PingFederate will migrate the modified file on upgrade and create a backup of the latest file. To take advantage of the new verbose logging capability, you must merge your modifications into the latest version of `log4j2.xml`. * Expired passwords and prompts to change passwords When using PingDirectory 8.2 or later as the credential store, if a user's password has expired, the following settings ensure PingFederate doesn't direct the user to the Change Password form when they enter an invalid password: * Set the **return-password-expiration-controls** setting in the PingDirectory password policy to **always**. * Starting with PingFederate 11.1, when configuring an LDAP Username Password Credential Validator, select the **Expect Password Expired Control** checkbox in the advanced fields section of the **Instance Configuration** tab of the **Create Credential Validator Instance** page. * Device authorization flows using the authentication API Starting with PingFederate 11.1, the user code verification steps of the device authorization flow are API-enabled. Existing API applications will need to be updated to support the new API states. To disable the use of the API for the new states, set `enable-authn-api-for-user-code-validation` to `false` in `/pingfederate/server/default/config-store/oauth-device-flow.xml`. This will cause PingFederate to continue to render these states itself using the Velocity templates. * Java 17 Starting with PingFederate 11.1, when using Java 17, the following JDKs are supported: * Adoptium OpenJDK * Oracle JDK * Amazon Corretto If you upgrade to Java 17 after you upgrade PingFederate: * Remove `-XX:-UseParallelOldGC` from the `jvm-memory.options` file. * Reinstall the Windows Service. * Certificate revocation checking Starting with PingFederate 11.1, when configured for certificate revocation list (CRL) *(tooltip: \
\

A list of revoked signing certificates, maintained by the issuing authority at a public URL.\

\
)* or Online Certificate Status Protocol (OCSP) *(tooltip: \
\

The protocol used by CAs to check the revocation status of an X.509 certificate.\

\
)* revocation checking, PingFederate now performs these checks in a broader range of flows. In particular, outbound TLS calls to retrieve JSON web key sets (JWKS) now perform revocation checks. Also, outbound TLS calls performed by plugins, such as adapters, now perform revocation checks. To revert to the previous behavior where PingFederate doesn't perform these new checks, set `pf.tls.installRevocationCheckerGlobally` to `false` in the `run.properties` file. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | CRL-based revocation checks can consume large amounts of memory. If CRL checking is enabled, you should set PingFederate's maximum heap in the `jvm-memory.options` file to at least 4 GB. Alternatively, consider switching to OCSP revocation checking, which demands fewer resources. | When configured for CRL or OCSP revocation checking, PingFederate's validation of CRLs and OCSP responses is tighter than before. The following settings in the `revocation-checking-config.xml` file control the new validation checks: * `crl-issuer-allow-any-trust-anchor` * `crl-verify-issuing-distribution-point` * `OCSP-enforce-responder-key-usage-check` Although you should leave the new validation checks enabled, you can disable them for compatibility with existing deployments. * Custom `MasterKeyEncryptor` implementations Starting with PingFederate 11.1, due to the revocation checking enhancements outlined above, a circular initialization dependency can arise if revocation checking is enabled and a custom `MasterKeyEncryptor` implementation makes API calls to an external service. To avoid this risk, you should disable revocation checking for any API calls made by the master key encryptor. Learn more about disabling revocation checking in custom `MasterKeyEncryptor` implementations in the PingFederate SDK documentation. * `run.sh` and `run.bat` files In PingFederate 11.1, the `run.sh` and `run.bat` files were updated. * A `startup` directory was added under the PingFederate installation. Its contents are now added to the classpath using a wildcard. * References to `jetty-start.jar` were updated in `run.sh` and `run.bat` because `jetty-start.jar` was moved from the `bin` directory to the `startup` directory. * References to `run.jar` were removed from `run.sh` and `run.bat` because `run.jar` was removed from the `bin` directory. If your `run.sh` or `run.bat` files were customized, you must update your copy of these files accordingly. * Template `username.recovery.template.html` Starting with PingFederate 11.1, the `username.recovery.template.html` template no longer includes the *$forgotPasswordUrl* variable. | | | | - | ------------------------------------------------------------------- | | | The top of the template file documents which variables you can use. | * Dynamic discovery settings In PingFederate 10.3.x or older, administrators could only define dynamic discovery settings to discover cluster membership in the `server/default/conf/tcp.xml` file. Now PingFederate provides a new configuration file for these settings, `bin/jgroups.properties`. This new approach streamlines future upgrade experiences. For new installations, we recommend defining dynamic discovery settings in the `jgroups.properties` file. While upgraded environments will continue to look for dynamic discovery settings from the `tcp.xml` file, we recommend performing a one-time migration to ease the upgrade experiences in the future. Learn more in [Migrating cluster discovery settings](../server_clustering_guide/pf_migrate_cluster_discovery_settings.html). * Velocity HTML templates Starting with PingFederate 11.0, if any of the default Velocity HTML templates for user-facing windows were modified, the Upgrade Utility migrates them to the new installation and renames the corresponding default templates in the new installation with the following format: `-default-.`. Learn more in [User-facing windows](pf_copying_custom_files_settings.html#_user_facing_windows). * Kerberos authentication Starting with PingFederate 11.0, when the new **Retain Previous Keys on Password Change** checkbox on the **Manage Domain/Realm** page is selected, PingFederate saves the encryption keys associated with the password of the current Kerberos service account. The checkbox is selected by default. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingFederate will not save the encryption keys until you re-save the configuration of the domain or realm. To facilitate seamless rotation of the service account password for existing domains, click **Save** on the **Manage Domain/Realm** page before you update the password in the domain controller. Learn more in [Adding Active Directory domains and Kerberos realms](../administrators_reference_guide/pf_adding_active_directory_domains_kerberos_realms.html). | * IWA IdP adapter PingFederate 11.0 and later no longer support the Integrated Windows authentication (IWA) *(tooltip: \
\

Internet Information Services (IIS) authentication protocol for authenticated connections between IIS and other Microsoft services.\

\
)* IdP adapter. The IWA integration kit for Kerberos has been replaced with a PingFederate adapter for Kerberos. See [Migrating from the Integrated Windows Authentication Integration Kit to the PingFederate Kerberos adapter](https://support.pingidentity.com/s/article/Migrating-from-the-Integrated-Windows-Authentication-integration-kit-to-the-PingFederate-Kerberos-adapter). * Private key JSON web token authentication When authenticating an OAuth client that uses the private key JSON Web Token (JWT) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* authentication scheme, PingFederate now validates that the issuer and subject claims in the JWT have the same value. The following administrative API endpoint exposes the validation on/off switch: ``` https://{{pf_base_host_port}}/pf-admin-api/v1/configStore/oauth-credentials-validator/issuerMustBeEqualToClientId ``` To disable validation, send an HTTP POST request with the following body to the endpoint: ```json { "id": "issuerMustBeEqualToClientId", "stringValue": "false", "type":"STRING" } ``` * Authentication API applications Starting with PingFederate 11.0, the new **Restrict Access to Redirectless Mode** checkbox on the **Authentication API Applications** page lets you restrict which authentication API applications can use redirectless mode. To avoid impacting existing deployments, this checkbox is not selected on upgrade. However, you should enable this setting. Learn more in [Managing authentication applications](../administrators_reference_guide/help_authenticationapplicationstasklet_authenticationapplicationsstate.html). * Jetty agent Starting with PingFederate 11.0, if your PingFederate server is running on a Java version prior to 8u252, you must modify your `run.sh`, `run.bat`, or `PingFederateService.conf` script to include the new Jetty agent in PingFederate. Add the following Java argument to the script: ``` -javaagent:/server/default/lib/jetty-alpn-agent.jar ``` Example for `run.sh`: ``` "$JAVA" $JAVA_OPTS \ $ERROR_FILE \ $HEAP_DUMP \ ${GC_FILE:+$GC_FLAG"$GC_FILE"$GC_OPTIONS} \ $ENDORSED_DIRS_FLAG \ -javaagent:$PF_HOME/server/default/lib/jetty-alpn-agent.jar \ -Dlog4j2.AsyncQueueFullPolicy=Discard \ ``` Example for `run.bat`: ``` "%JAVA%" %PF_JAVA_OPTS% %JAVA_OPTS% %GC_OPTION% -javaagent:%PF_HOME%/server/default/lib/jetty-alpn-agent.jar -Dlog4j2.AsyncQueueFullPolicy=Discard ``` Example for `PingFederateService.conf` (note the extra `../` because this is located in `pingfederate/sbin/wrapper`): ``` # Java Additional Parameters wrapper.java.additional.1=-Dlog4j.configurationFile=../../server/default/conf/log4j2.xml ...... (omitted lines 2-13 to save space) ...... wrapper.java.additional.14=-javaagent:../../server/default/lib/jetty-alpn-agent.jar ``` * Specifying a maximum size for inbound runtime requests Starting with PingFederate 11.0, if you have previously specified a value for `maxFormContextSize` in `jetty-runtime.xml`, you should now use `pf.runtime.http.maxRequestBodySize` in the `run.properties` file to control the maximum size for inbound runtime requests. Learn more in [Configuring PingFederate properties](../administrators_reference_guide/pf_config_pf_propert.html). * Java 8 As we continue to improve our products and HSM integrations, you should migrate off of Java 8. We intend to remove Java 8 support from our qualification process in May 2023. You can find more information, including about Java 11 support, in [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html). * Third-party integrations As we continue to improve PingFederate, we intend to remove the following product releases from our qualification process after the release of PingFederate 11.3 in June 2023: * Oracle Linux 7.9 (Red Hat-compatible Kernel) * Red Hat Enterprise Linux 7.9 * Microsoft SQL Server 2016 SP2 * Oracle Database 12c Release 2 * Microsoft Windows Server 2012 R2 * Microsoft Active Directory 2012 R2 We encourage you to upgrade these products to more recent versions, such as: * Oracle Linux 8.5 (Red Hat-compatible Kernel) * Red Hat Enterprise Linux 8.5 * Microsoft SQL Server 2017 * Oracle Database 19c * Microsoft Windows Server 2016 * Microsoft Active Directory 2016 Find a more complete list of qualified third-party solutions in [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html).