Upgrade considerations introduced in PingFederate 11.x
The following modifications since PingFederate 11.0 might affect existing deployments.
- 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 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<pf_install>/pingfederate/server/default/conf/
directory. On first startup, PingFederate processesservice-points.conf
and generates a defaulthivemodule.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. For more information, see Overriding configuration settings using environment variables.When you upgrade a supported version of PingFederate older than 11.3 to version 11.3 or later, the
service-points.conf
file replaces thehivemodule.xml
file in the<pf_install>/pingfederate/server/default/conf/META-INF/
directory with a generated defaulthivemodule.xml
file in<pf_install>/pingfederate/server/default/conf/generated-hivemodule/META-INF/
directory.If you want to continue using
hivemodule.xml
instead ofservice-points.conf
, addhivemodule.xml
to the directory<pf_install>/pingfederate/server/default/conf/META-INF/
after upgrading PingFederate. During startup, if PingFederate findshivemodule.xml
in that directory, it will ignoreservice-points.conf
. Later, when you upgrade PingFederate 11.3 or a newer version, thehivemodule.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<pf_install>/pingfederate/server/default/conf/generated-hivemodule/META-INF/
. Copy and, if needed, modifyhivemodule.xml
. Use that file to launch your production PingFederate instance. When you launch PingFederate, your existing process can grabhivemodule.xml
and work as expected. -
Disable your process that needs to work with
hivemodule.xml
directly. If needed, modify theservice-points.conf
file that comes with PingFederate 11.3 or later. When you launch PingFederate, it generateshivemodule.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 generateshivemodule.xml
.
-
- Configuration change necessary for MFA adapters
-
As of PingFederate 10.2, when you define policies using multi-factor authentication (MFA) adapters, you must select the User ID Authenticated check box in the Incoming User ID popup to allow users to register as a new MFA user. You should only select this check box if the previous authentication source has verified the Incoming User ID. You should not select the check box if the MFA adapter is part of a policy used for password reset or password change. For more information, see Defining authentication policies.
Administrators using the PingID adapter must review existing policies and select this check box if appropriate. Otherwise, the adapter will prevent new user registration.
- LDAP properties
-
Starting with PingFederate 11.3, the
<pf_install>/pingfederate/bin/ldap.properties
file includes the newldap.type
field. This mandatory field specifies the LDAP directory server type. If you use LDAP for administrative console or administrative API authentication, ensure you set this field to a valid value. - Refresh token rolling grace period
-
When upgrading from PingFederate versions later than 11.0.1, if the Authorization Server Settings window was never modified, a default value of 0 shall be set for Refresh Token Rolling Grace Period. If the Authorization Server Settings window was modified, the previously set value shall be retained. For more information, see the Refresh Token Rolling Grace period field in Configuring authorization server settings.
- Metadata response configuration
-
Starting with PingFederate 11.2, PingFederate provides an OAuth authorization server metadata endpoint,
/.well-known/oauth-authorization-server
. The new endpoint returns configuration information that OAuth clients need to interface with PingFederate using the OAuth 2.0 protocol. You can customize what information the endpoint returns by editing the<pf_install>/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 AWS 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. For more information on limitations, see the Hardware security modules (HSM) issue section of the Release Notes. In addition, the
java.security
file in the Java Runtime Environment (JRE) no longer needs to be modified and client files do not need to be copied to theJAVA_HOME/jre/lib/ext
directory. For more information on how to upgrade the HSM client, see the updated setup instructions in Integrating with AWS CloudHSM. - Verbose logging
-
Starting with PingFederate 11.2, you can enable verbose logging with the Log Settings window or with the administrative API on nodes that have the updated version of the
<pf_install>/pingfederate/server/default/conf/log4j2.xml
file. Iflog4j2.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 oflog4j2.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 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
tofalse
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 thejvm-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
tofalse
in therun.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 customMasterKeyEncryptor
implementations.run.sh
andrun.bat
files-
In PingFederate 11.1, the
run.sh
andrun.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 inrun.sh
andrun.bat
becausejetty-start.jar
was moved from thebin
directory to thestartup
directory. -
References to
run.jar
were removed fromrun.sh
andrun.bat
becauserun.jar
was removed from thebin
directory.
-
If your
run.sh
orrun.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 thejgroups.properties
file. While upgraded environments will continue to look for dynamic discovery settings from thetcp.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:
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:
{ "id": "issuerMustBeEqualToClientId", "stringValue": "false", "type":"STRING" }
- 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
, orPingFederateService.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 inpingfederate/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
injetty-runtime.xml
, you should now usepf.runtime.http.maxRequestSize
in therun.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.
-