PingFederate Server

Upgrade considerations introduced in PingFederate 10.x

Several specific modifications since PingFederate 10.0 might affect existing deployments.

Delayed heartbeat response due to archive import on startup

Starting with version 10.2, when you place an archive in the <pf_install>/pingfederate/server/default/data/drop-in-deployer directory on startup, the heartbeat endpoint will not return 200 until archive import completes. Depending on how long archive import and configuration loading takes, the first successful heartbeat response may be significantly delayed relative to earlier versions. If you have configured a health check or probe that can trigger a restart of the server, crash loop behavior can result. Review the configuration of these checks to ensure time thresholds are set appropriately.

TLS 1.0 and 1.1 disabled

Starting with version 10.3, PingFederate disables TLS 1.0 and 1.1 for both inbound and outbound connections by default. As a result, clients using TLS 1.0 or 1.1 will no longer be able to connect to the administrative port or the runtime port. If you must re-enable TLS 1.0 or 1.1, add TLSv1 or TLSv1.1 to the run.properties file: look for the “TLS Protocol Settings” section and follow the inline instructions. Additionally, you might need to add back the weaker cipher suites, such as TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, or TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA. For more information, see Managing cipher suites.

Bouncy Castle FIPS mode

When upgrading an installation where Bouncy Castle FIPS mode is enabled, it is no longer necessary to place the bc-fips jar file in the JAVA_HOME/jre/lib/ext directory. It is also no longer necessary to modify the JAVA_HOME/jre/lib/security/java.security file. It is recommended to revert these changes to the Java environment.

SameSite cookie configuration

As of PingFederate 10.3, the Jetty configuration uses the native servlet SameSite cookie configuration. This moves the SameSite specifier declaration to its own attribute in the Jetty configuration as follows:

  • New format for jetty-admin.xml in the DeploymentManager:

    <Call name="setContextAttribute">
    <Arg>org.eclipse.jetty.cookie.sameSiteDefault</Arg>
    <Arg>None</Arg>
</Call>

  • New format for jetty-runtime.xml in the WebAppContext:

    <Call name="setAttribute">
    <Arg>org.eclipse.jetty.cookie.sameSiteDefault</Arg>
    <Arg>None</Arg>
</Call>

  • If you want to specify a default value for session management cookies, such as JSESSIONID, in servlets hosted in PingFederate, add a <comment> like the one in the following snippet to the existing session-config in the web.xml file:

    <session-config>
    <session-timeout>30</session-timeout>
        <cookie-config>
            <http-only>true</http-only>
            <!--
                The following comment adds a default SameSite value to the JSESSIONID cookie in any servlet context.
                Available options are:
                    SAME_SITE_NONE
                    SAME_SITE_LAX
                    SAME_SITE_STRICT
            -->
         <comment>SAME_SITE_NONE</comment>
    </cookie-config>
</session-config>
Microsoft Internet Explorer 11

Ping Identity commits to deliver the best experience for administrators and users. As we continue to improve our products, we encourage our customers to migrate off of Microsoft Internet Explorer 11. We intend to remove Internet Explorer 11 from our qualification process in December 2021.

Microsoft Windows Server 2012 R2 and Active Directory 2012

Because Microsoft will end extended support for Windows Server 2012 R2 in late 2023 (see here), you should upgrade your Windows servers and Active Directory to a later version, such as Windows Server 2019. For a full list, see System requirements. We intend to remove Windows Server 2012 R2 and Active Directory 2012 from our qualification process in July 2023.

Authorization endpoint

Before version 10.2, PingFederate did not validate the NumericDate value of exp claims in a signed request object’s JWT. To ensure the JWT does not expire too far in the future, PingFederate 10.2 and later do validate the value. PingFederate rejects any JWT that expires more than 720 minutes later. You can change that default value in <pf_install>/pingfederate/server/default/data/config-store/jwt-request-object-options.xml.

PingFederate interprets the NumericDate value as seconds, not milliseconds. So PingFederate 10.2 will reject a JWT that has the NumericDate value based on milliseconds, because PingFederate calculates the JWT to live more than 720 minutes.
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.
Expression Admin role

When upgrading to PingFederate 10.1 or later from an earlier version, administrative users who were granted the Admin role in the earlier installation are granted the Expression Admin role automatically. You can achieve the same result by using the /bulk/import administrative API endpoint to bulk-import a configuration that was bulk-exported from PingFederate 10.0.Additionally, all four administrative roles, namely User Admin, Admin, Expression Admin, and Crypto Admin, are required to access and make changes through the following services:

  • The /bulk, /configArchive, and /configStore administrative API endpoints

  • The System → Server → Configuration Archive window in the administrative console

  • The Connection Management configuration item on the Security → System Integration → Service Authentication window

Authentication session created after user registration

As of PingFederate 10.1, an authentication session is automatically created for a user after registration, preventing the user from having to log in again during the next SSO transaction. This feature is enabled by default for all new and existing local identity profiles. However, if needed, you can disable it through the /localIdentity/identityProfiles administrative API endpoint by setting the createAuthnSessionAfterRegistration attribute to false.

Template html.form.login.template.html

Starting with PingFederate 10.0, the html.form.login.template.html template no longer includes the $forgotPasswordUrl variable.