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 window.
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 <pf_install>/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 Correto
If you upgrade to Java version 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) or online certificate status protocol (OCSP) 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. Refer to the SDK documentation for more information on how to disable revocation checking in custom MasterKeyEncryptor implementations.
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 versions preceding PingFederate 11.0, 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. For more information, see Migrating cluster discovery settings.
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: <template_name>-default-<PF-version>.<ext>. For more information, see User-facing windows.
Kerberos authentication
Starting with PingFederate 11.0, when the new Retain Previous Keys on Password Change check box on the Manage Domain/Realm window is selected, PingFederate saves the encryption keys associated with the password of the current Kerberos service account. The check box 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 window before you update the password in the domain controller. For more information, see Adding Active Directory domains and Kerberos realms.

IWA IdP adapter
PingFederate 11.0 and later no longer support the integrated Windows authentication (IWA) 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.
Private key JSON web token authentication
When authenticating an OAuth client that uses the private key JSON web token (JWT) 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:
To disable validation, send an HTTP POST request with the following body to the endpoint:
  "id": "issuerMustBeEqualToClientId",
  "stringValue": "false",
Authentication API applications
Starting with PingFederate 11.0, the new Restrict Access to Redirectless Mode check box on the Authentication API Applications window lets you restrict which authentication API applications can use redirectless mode. To avoid impacting existing deployments, this check box is not selected on upgrade. However, you should enable this setting. For more information, see Managing authentication applications.
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:


Example for run.sh:

-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

...... (omitted lines 2-13 to save space) ......

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.maxRequestSize in the run.properties file to control the maximum size for inbound runtime requests. For more information, see Configuring PingFederate properties.
Java 8
As we continue to improve our products and hardware security module (HSM) integrations, you should migrate off of Java 8. We intend to remove Java 8 support from our qualification process in May 2023. For more information, including Java 11 support, see System requirements.
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

For a more complete list of qualified third-party solutions, see System requirements.