PingFederate 11.2 (December 2022) - PingFederate - 11.3

PingFederate Server

PingFederate Server
PingFederate 11.3
Product documentation
Guide > Administrator Guide

New features and improvements in PingFederate 11.2.

Support for OAuth 2.0 authorization server metadata


PingFederate now supports OAuth 2.0 authorization server metadata. This allows OAuth clients to retrieve relevant endpoints and other details about features that PingFederate supports. The API response is like the OpenID Connect Discovery endpoints response but doesn't include OpenID Connect relevant details. This lets you configure endpoints for your particular use case. See OAuth authorization server metadata endpoint.

Support for nested groups and nested search for PingDirectory


For outbound provisioning, PingFederate now supports nested groups and nested search for PingDirectory. This lets you freely choose your favorite directory without needing to choose based on the support for nested groups. See nested group and nested search in Specifying a source location.

Exposed AccessGrantManagerAccessor as part of the SDK


The AccessGrantManagerAccessor is now accessible in the PingFederate SDK. This lets developers query existing persistent grants at run time. See <pf_install>/pingfederate/sdk/doc/com/pingidentity/access/AccessGrantManagerAccessor.html in the SDK documentation.

Improved the sign-on experience after users change their password


Now you can configure PingFederate to keep users signed in after they change their password. This prevents users from having to sign on again, right after updating their password, improving the user experience. See the Require Re-authentication settings HTML Form Adapter advanced fields.

Administrative API supports multiple authentication and authorization schemes


Now you can configure the PingFederate administrative API to accept either OAuth access_token or basic authentication. This is especially useful in cases where applications shouldn't include administrator’s credentials in API requests. See pf.admin.api.authentication in Configuring PingFederate properties.

Support for Google reCAPTCHA v3 and integration with multiple CAPTCHA providers


PingFederate now supports Google reCAPTCHA v3. reCAPTCHA v3 produces a score between 0.0 - 1.0 (risky to safe) that you can use in policies to require step-up authentication or other actions. By default, reCAPTCHA v3 doesn't interrupt user journeys, which are in the control of application developers. See Managing CAPTCHA providers.

PingFederate also now provides an SDK that allows for integrations with custom CAPTCHA providers, which adds great flexibility to the CAPTCHA feature.

Improved cluster replication notification


Instead of showing an active bell icon, the administrative console now displays a banner when cluster replication is required. The banner includes a link to the Cluster Management window for easy access. See Cluster management.

The administrative console supports OIDC claims parameter


You can configure PingFederate to function as an OpenID Connect client and let administrators sign on to the administrative console using their PingOne credentials. PingFederate initiates an OpenID Connect flow that includes the claims parameter. You can also use this feature outside the PingOne environment, leveraging any authorization server that supports the claims parameter. This allows for a simpler, seamless login flow. See Request Parameters in Enabling OIDC-based authentication.

The administrative console supports third party-initiated login


You can configure PingFederate to accept incoming parameters, such as iss, that are processed and included in an outgoing authorization request if configured to do so. This feature lets administrators sign on to PingFederate from PingOne. This feature also supports other OpenID Connect authorization servers that support incoming parameters. See Request Parameters in Enabling OIDC-based authentication.

PingOne DaVinci integration kit


The PingFederate distribution now includes the PingOne DaVinci integration kit. See PingOne DaVinci Adapter in Bundled adapters and authenticators.

Amazon DynamoDB and persistent authentication sessions


PingFederate can now manage persistent user sessions in AWS DynamoDB. Persistent user sessions keep sessions active even after a restart of PingFederate. This feature reduces the interruption of user journeys. See Configuring an Amazon DynamoDB for persistent authentication sessions in Defining a datastore for persistent authentication sessions.

Enhanced policy rules


When defining policy rules, now attributes that were processed in an earlier step can be accessed further down in the policy tree. This feature enhances the management and usability of policies. See Configuring rules in authentication policies.

The heartbeat endpoint and JMX expose more information


The data exposed by the heartbeat endpoint and JMX interface now include more details, such as the number of errors per data store. See Liveliness and responsiveness.

Updated the bundled PingOne MFA Adapter


Updated the bundled PingOne MFA Adapter to the newest version, 2.0. See PingOne MFA Adapter in Bundled adapters and authenticators.

Toggle log verbosity with ease


Gone are the days you had to edit the log4j2.xml file on multiple servers to enable or disable DEBUG messages in their server logs. Now you can toggle log settings in the administrative console or with the administrative API.

PingFederate provides a set of message categories, each targeting a specific scenario. For example, the XML Signatures category helps you troubleshoot XML signature issues. You can also add your own categories to suit your unique requirements.

Timestamps for clients and connections


When viewing lists of OAuth clients and Browser single sign-on (SSO)/security token service (STS) connections, you can now sort them by modification or creation time. The timestamps can also help you understand the history and the relationship between clients and connections.

AWS CloudHSM and Java 11


If you integrate with Amazon Web Services (AWS) CloudHSM, now you can choose between Java 8 and Java 11.

OAuth Rich Authorization Requests


OAuth rich authorization requests (RAR) provide a standard way for OAuth client applications to specify fine-grained authorization requirements in their requests. For example, when initiating a money transfer, a personal banking application can pass all relevant information to the authorization server via the new parameter authorization_details. The authorization server supporting RAR processes the authorization_details parameter value accordingly and ultimately returns tokens to the application if the process completes successfully.

RAR is on track to become a requirement in Financial-grade API (FAPI) 2.0. With this new capability, you can confidently build your open banking solutions with PingFederate.

Other enhancements


Now you can optionally define a sender name for each SMTP notification publisher instance.

PingFederate now supports XML Encryption 1.1.

Sorting LDAP and database-related fields


For LDAP and database-related fields, PingFederate now sorts values alphabetically and in case-insensitive order.

Detailed comments added to log4j2.xml file


We've added detailed comments to the log4j2.xml file to prevent misconfigurations that could lead to service hangs and production outages. For more information on logging, see Log4j 2 logging service and configuration.

Configuration options added to control SAML error responses


We've added a configuration option to control whether SAML error responses include Cause. The new setting is IncludeErrorCauseInSamlResponse in config-store/org.sourceid.saml20.protocol.StatusResponseTypeUtil.xml. The default value is true.

Improved SP STS message customization


The #HttpServletRequest and #HttpServletResponse variables are now available in SP STS message customization. For more information, see Message types and available variables.

Connections with multiple protocol types


We've resolved an issue where connections with multiple protocol types would only filter on a single protocol type.

OpenID Connect (OIDC) for administrative console authentication


When using OIDC for administrative console authentication, PingFederate no longer throws an NPE if private_key_jwt is used for client authentication method and the client.secret property is not set.

Improvements to refresh token rolling criteria


We've introduced a new separate stored value to track when refresh tokens should be reissued to OAuth clients, resolving a defect where rolling refresh tokens read the incorrect update timestamp to determine refresh token rolling criteria. For more information, see Configuring authorization server settings.

Store clients with special characters


When adding clients to Active Directory (AD) or other LDAP stores, PingFederate now automatically escapes reserved characters from clientIDs.

Improved detection around invalid Group DN


We've improved detection around invalid Group distinguished names (DN) and added exceptions in the provisioner log. For more information on Group DN, see Specifying a source location.

Updates to the SameSite=None header attribute supported browsers list


We've updated the supported browsers list for the SameSite=None header attribute to filter out problematic clients with the SameSite cookie attribute bug: Safari version 12 and Embedded Apple Webkit Browser Safari 12 on macOS.

Expired user sessions and session log out


PingFederate's administrative console now identifies expired user sessions on timeout and properly removes the session regardless of user interaction.

Policy and fragment logging


PingFederate now logs the policy and fragment name before fragment processing.

Bulk import for IdP connections


Resolved an issue where bulk import fails for identity provider (IdP) connections that fulfill Persistent Grant Extended Attributes.

Template double-submission


PingFederate templates no longer allow double-submission.

Connection failures on external LDAP authentication login


PingFederate now recovers from initial connection failure when logging into the administrative console using external LDAP authentication.

Hiding user information from authentication API responses


You can now configure the IncludeUserInfoInResponses setting in the <install dir>/server/default/data/config-store/org.sourceid.saml20.domain.mgmt.impl.AuthnApiManagerImpl.xml file to hide user information from authentication API responses.

Errors on policy fragments configured to handle failures locally


When an error occurs on policies containing fragments and configured to handle failures locally, PingFederate no longer redirects a user to the service provider (SP) error page on SP-initiated SSO.

Password management


We've resolved an issue around password requirements messaging during password management.

Updated description text on Import Connections page


We've updated the description text on the import IdP/SP connection page to indicate that PingFederate only performs minimal validation for imported connections. We suggest using the administrative API for connection migration, which performs thorough validation.

OTL for password reset expiry or reuse error reporting


In the case where a one-time link (OTL) for password reset expires or is reused, PingFederate now responds with the appropriate error message in the authentication API and logs the error response in the audit.log. For more information on OTL for password reset, see Configuring self-service account recovery.

Duplicate scope and scope group name values


We've resolved a defect that allowed scope and scope group names to be the same when saved through the administrative console. For more information on scopes, see Scopes and scope management.

Warning during SQL provisioning table creation


We've decreased the maximum key length for saasGroupName, resolving a warning that occurred when creating SQL provisioning tables.

'Change Password' link accessibility


On sign-on pages, we've improved the accessibility of the 'Change Password' link, regardless of browser window size.

Notification publisher accessor added to SDK


We've added a notification publisher accessor to the SDK, addressing an error where plugins utilizing a notification publisher could not invoke one of the notification publishers configured in PingFederate.

Fragment processing now independent of policy processing


PingFederate now processes policy fragments independently from policies and other fragments.

LIP registration via a third-party service and the authentication API


We've resolved a defect where Local Identity Profile (LIP) registration via a third-party service and the authentication API would still require a password, despite previously registering with the third party.

PingID password credential validator with integrated RADIUS server


PingFederate versions 11.1.4, 11.1.5, 11.2.1, and 11.2.2 contain version 3.0.2 of the PingID password credential validator (PCV). That version of the PCV has known issues that you should review before upgrading. For more information, see Known issues in PingID RADIUS PCV 3.0.2.

Administrative console and administrative API

  • /bulk: Only resource types currently supported by the administrative API are included in the exported data. We don't intend to introduce administrative API support to the following areas:
  • Previously, the administrative API did not accurately reflect a Persistent Grant Max Lifetime setting of 29 days (or shorter) with the selection of the Grants Do Not Timeout Due To Inactivity option. As a result, if you have configured such OAuth authorization server settings and have generated a bulk export in version 10.0 through 10.0.2, we recommend that you re-generate a new bulk export after upgrading to version 10.0.3 (or a more recent version). The newly exported data does not contain the aforementioned flaw, and you can safely import it to version 10.0.3 (or a more recent version).
  • When enabling mutual TLS certificate-based authentication, administrators often configure a list of acceptable client certificate issuers. When you use a browser to access the console or the administrative API documentation, PingFederate returns to the browser the list of acceptable issuers as part of the TLS handshake. If the browser's client certificate store contains multiple client certificates, the browser often presents you only the certificates whose issuer matches one of the acceptable issuers. However, when PingFederate runs in a Java 11 environment, Chrome presents you all its configured client certificates, regardless of whether the issuer matches one of the acceptable issuers or not.
  • Prior to toggling the status of a connection with the administrative API, you must ensure that any expired certificates or no longer available attributes are replaced with valid certificates or attributes; otherwise, the update request fails.
  • When creating or updating a child instance of a hierarchical plugin, the administrative API retains objects with an "inherited": false name/value pair (or without such name/value pair altogether), ignores those with a value of true, and returns a 200 HTTP status code. No error messages are returned for the ignored objects.
  • Using the browser's navigation mechanisms (for example, the Back button) causes inconsistent behavior in the administrative console. Use the navigation buttons provided at the bottom of windows in the PingFederate console.
  • Using the PingFederate console in multiple tabs on one browser might cause inconsistent behavior which could corrupt its configuration.
  • If authenticated to the PingFederate administrative console using certificate authentication, a session that has timed out might not appear to behave as expected. Normally (when using password authentication), when a session has timed out and a user attempts some action in the console, the browser is redirected to the sign-on page, and then back to the administrative console after authentication is complete. Similar behavior applies for certificate authentication, in principle. However, because the browser might automatically resubmit the certificate for authentication, the browser might redirect to the administrative console and not the sign on page.



For Java versions that don't support TLSv1.3 (meaning versions earlier than 8u261), PingFederate fails on start up with a NoSuchAlgorithmException exception. To resolve this error, remove TLSv1.3 from the following settings in the file:

  • pf.tls.client.protocols
  • pf.tls.runtime.server.protocols
  • pf.tls.admin.server.protocols

TLS cipher suite customization


PingFederate's TLS cipher suites can be customized by modifying com.pingidentity.crypto.SunJCEManager.xml (or a similarly-named file if BCFIPS or a hardware security module (HSM) is configured). After updating the file and replicating, all cluster nodes must be restarted for the change to take effect.


  • As of PingFederate 11.1, BC-FIPS and HSMs are not supported when using Java 17.
  • Updating Java version 8 to version 11 results in an error when PingFederate is already installed and running. To work around this issue, uninstall and reinstall the PingFederate Windows service by running the UninstallPingFederateService.bat and InstallPingFederateService.bat files located in <pf_install>/pingfederate/sbin/wrapper.

Hardware security modules (HSMs)

  • It is not possible to use an elliptic curve (EC) certificate as an SSL server certificate.
  • TLS 1.3 is not currently supported.
Thales HSMs
  • JWT token decryption using ECDH-ES may fail. This issue only arises if PingFederate is configured with static OAuth and OpenID Connect keys, a static key is stored on the HSM, and PingFederate is consuming a token encrypted with this key.
  • It is not possible to use an elliptic curve (EC) certificate as an SSL server certificate.
  • TLS 1.3 is not currently supported.
Entrust HSMs
  • PingFederate must be deployed with Oracle Server Java Runtime Environment (JRE) 8 or Amazon Corretto 8.
  • JWT token decryption using ECDH-ES or RSAES OAEP may fail. This issue only arises if PingFederate is configured with static OAuth and OpenID Connect keys, a static key is stored on the HSM, and PingFederate is consuming a token encrypted with this key.
  • SAML assertion decryption using RSA OAEP may fail when the decryption key is stored on the HSM.
  • It is not possible to use an elliptic curve (EC) certificate as an SSL server certificate.
  • TLS 1.3 is not currently supported.


  • When consuming SAML metadata, PingFederate does not report an error when neither the validUntil nor the cacheDuration attribute is included in the metadata. Note that PingFederate does reject expired SAML metadata as indicated by the validUntil attribute value, if it is provided.
  • The anchored-certificate trust model cannot be used with the Single log off (SLO) redirect binding because the certificate cannot be included with the logout request.
  • If an IdP connection is configured for multiple virtual server IDs, PingFederate will always use the default virtual server ID for IdP Discovery during an SP-initiated SSO event.

Composite Adapter configuration


SLO is not supported when users are authenticated through a Composite Adapter instance that contains another instance of the Composite Adapter.

Self-service password reset


Passwords can be reset for Microsoft Active Directory user accounts without the permission to change password.



PingFederate does not support a case-sensitive naming convention for OAuth client ID values when client records are stored in a directory server. For example, after creating a client with an ID value of sampleClient, PingFederate does not allow the creation of another client with an ID value of SampleClient.

Although it's possible to create clients using the same ID values with different casings when client records are stored in XML files, a database server, or custom storage, we recommend not doing so to avoid potential record migration issues.

Customer identity and access management


Some browsers display a date-picker user interface for fields that have been designed for date-specific inputs. Some browsers do not. If one or more date-specific fields are defined on the registration page or the profile management page (or both), end users must enter the dates manually if their browsers do not display a date-picker user interface for those fields.


  • LDAP referrals return an error and cause provisioning to fail if the user or group objects are defined at the DC level, and not within an OU or within the Users CN.
  • The totalResults value in SCIM responses indicates the number of results returned in the current response, not the total number of estimated results on the LDAP server.


  • If a source attribute has been configured for masking in an IdP adapter or IdP connection and the source attribute is mapped to OAuth's persistent grant USER_KEY attribute, the USER_KEY attribute will not be masked in the server logs. Other persistent grant attributes will be masked.
  • Even if a source attribute has been configured for masking in an IdP adapter and the source attribute is mapped as the adapter's unique user key, the user key attribute is not masked in the server or audit logs.

Database logging

  • If a source attribute has been configured for masking in an IdP adapter or IdP connection and the source attribute is mapped to OAuth's persistent grant USER_KEY attribute, the USER_KEY attribute will not be masked in the server logs. Other persistent grant attributes will be masked.
  • Even if a source attribute has been configured for masking in an IdP adapter and the source attribute is mapped as the adapter's unique user key, the user key attribute is not masked in the server or audit logs.



The RADIUS NAS-IP-Address is only included in Access-Request packets when the pf.bind.engine.address is set with an IPv4 address. IPv6 is not supported.

PingOne Fraud integration kit

PingOne Fraud
The PingOne Fraud integration kit is no longer bundled with PingFederate.

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 you to migrate off of Microsoft Internet Explorer 11. Starting with PingFederate 11.0, Internet Explorer 11 is no longer included in the PingFederate qualification process for administrators or users. For a list of supported browsers, see System requirements.

Configcopy tool, Connection Management Service, SSO Directory Service


As of PingFederate 10.2, these features have been deprecated and will be removed in a future release.

Oracle Directory Server Enterprise Edition


As Oracle ended its Premier Support for Oracle Directory Server Enterprise Edition (ODSEE 11g) in December 2019, we no longer include ODSEE as part of the PingFederate qualification process (starting with PingFederate 10.2). We continue to qualify against Oracle Unified Directory ( and other supported directory servers. For a full list, see System requirements.



Starting with PingFederate 10.2, monitoring and reporting through the Simple Network Management Protocol (SNMP) has been removed.

Roles and protocols


Starting with PingFederate 10.1, roles and protocols are always enabled and no longer configurable through the administrative console and API.

S3_PING discovery protocol


Starting with PingFederate 10.1, the S3_PING discovery protocol has been deprecated. Customers running on AWS infrastructure should instead use NATIVE_S3_PING.

Red Hat Enterprise Linux install script


Starting with PingFederate 10.0, the Red Hat Enterprise Linux install script is no longer available. To install PingFederate 10.0 for Linux, you must download and extract the product distribution .zip file.