Administrative APIs
Bulk export and import
PingFederate offers a set of administrative APIs as an alternative to the administrative console to manage various configuration objects. Version 10 allows administrators to make one request to bulk export administrative API-enabled configuration objects in JSON. As needed, administrators can edit this JSON and make a single request to bulk import their modifications. This new capability can simplify the movement of configuration from one environment to another.
Configuration files in a config-store directory
Some advanced setups require the editing of individual configuration files in the config-store directory. With PingFederate 10, administrators can make administrative API requests to retrieve and update these files.
Furthermore, administrators can use JSON obtained from the bulk export to locate the files in the config-store directory that have been modified and determine what those changes are. If files in the config-store directory were previously modified without record-keeping, this capability makes it easy to establish such an inventory to deliver a reliable audit of changes.
Custom ID values in administrative API requests
When creating new configuration objects via the administrative API, API clients can now supply the desired IDs in the requests. With this optional capability, administrators no longer find themselves making a follow-on request only to retrieve the system-generated ID of a newly created configuration object. Instead, administrators can manage IDs of new configuration objects outside of PingFederate, which simplifies the orchestration of configuration objects with the dependency requirements of other objects.
Authentication APIs and policies
Identifier First Adapter
The PingFederate authentication API, introduced in version 9.3, decouples the authentication policies managed by PingFederate administrators and the presentation layer managed by front-end developers. Like the HTML Form Adapter, the Identifier First Adapter is now authentication API-enabled.
Postman collection
The Authentication API Explorer provides a user-friendly environment to demonstrate the capability of the authentication API. In PingFederate 10, a Postman collection is now available from the Authentication API Explorer, which includes states and actions from all the deployed authentication adapters and selectors that are authentication API-capable, to enrich the learning experience.
Cluster Node Authentication Selector enhancement
Previously, administrators may define authentication requirements based on the cluster node index values by using instances of the Cluster Node Authentication Selector in authentication policies. Beginning with version 10, administrators may also do so based on the tags that they apply to any nodes in the cluster to easily apply logic to a group of nodes. This added capability is well-suited for environments where PingFederate nodes are dynamically discovered and bootstrapped without a preconfigured node index value.
Datastore integration
Specify datastore connection strings based on tags
When configuring a new or an existing datastore, an administrator can now define multiple connection strings and apply node tags to each of them. When servicing requests that involve a datastore operation, the processing node selects the connection string that it should use based on the tags found in the datastore configuration and the tags applied to the node itself.
If PingFederate cannot determine a connection string based on tags, it uses the default connection string as designated by the administrator in the datastore configuration. This flexibility provides administrators an opportunity to optimize datastore-related traffic based on regional infrastructure.
Follow LDAP referrals
Administrators can configure new or existing LDAP datastores to follow the LDAP referrals sent back by the directory servers. This improvement allows new use cases, such as establishing a datastore connection to a read-only Active Directory Domain Controller while still allowing end users to change or reset their passwords through it by leveraging a referral.
Option to bypass external validation
In the past, the management of datastores or the configuration objects that use them requires such datastores to be reachable. While this connectivity test guarantees the validity of such datastores at the time of configuration, it restrains administrators' ability to manage PingFederate configuration in a more offline fashion. Starting with version 10, the connectivity test is an optional step when managing datastores through the administrative console. Additionally, when creating or updating datastores or the configuration objects that use them via administrative API requests, administrators have the option to bypass such a validation.
Token exchange
PingFederate 10 introduces support for the OAuth 2.0 Token Exchange specification (https://tools.ietf.org/html/rfc8693). This specification defines an open standard for the exchange of security tokens from an authorization server. This allows resource servers, for example, to exchange access tokens for other security tokens that are required to call additional APIs, much like what is required in a microservices architecture. PingFederate’s native support of subject tokens and actor tokens opens up new use cases around delegation and impersonation, which ultimately enriches the end-user experience as resources flow through seamlessly among the backend services used by the user-facing applications.
Mapping from authentication source into OpenID Connect policy
Previously, to map from an IdP Adapter instance, an IdP connection, or an authentication policy contract into an OpenID Connect (OIDC) policy contract, administrators must map such attributes into an access token attribute contract and then use the access token as the source of attributes when fulfilling an OIDC policy contract. PingFederate now provides an alternative to simplify these mappings. An administrator can now add extended attributes to the persistent grant contract, map from those sources into the grant, and then use the grant as the source of attributes when fulfilling an OIDC policy contract. This new mapping configuration eliminates the need for creating multiple ATMs, OIDC policies, and mapping configurations for the sole purpose of shielding attributes from the front-channel.
Enhancement in refresh token use cases
For OAuth clients capable of using the OpenID Connect (OIDC) protocol and the OAuth 2.0 refresh token grant type, administrators may configure the OIDC policies associated with these clients to return ID tokens as the clients use their refresh tokens. This feature improves interoperability with third parties such as Kubernetes. Furthermore, when clients present their refresh tokens to the OAuth 2.0 introspection endpoint, PingFederate now includes expiry information (if any) in its responses.
Browser SSO and STS
WS-Federation SP and IdP connections now support the SAML 2.0 WS-Federation token type and custom schemes other than http:// and https:// for partner's service URLs. Furthermore, WS-Federation SP connections now support WS-Trust version 1.3 when building security token responses.
Message customization for STS
PingFederate 10 extends the message customization capability to WS-Trust STS use cases. Specifically, administrators can now use attribute mapping expressions to customize protocol messages in STS SP connections and through instances of SAML 1.1 and 2.0 Token Generators.
DevOps automation
Additional dynamic discovery protocols
We continue to modernize PingFederate for DevOps practices. Administrators may now use Native S3 PING or DNS_PING as the discovery protocol to support elastic scaling in the infrastructure of their choice. JGroups has been upgraded to version 4.1.4 to provide support for the newly added protocols (Native S3 PING, DNS_PING) and to keep the PingFederate clustering model up to date.
Native S3 PING
Similar to S3_PING, cluster membership information is automatically maintained in an Amazon Simple Storage Service (Amazon S3) bucket. However, instead of using access and secret keys directly, access to the S3 bucket is controlled via IAM profiles.
This mechanism leverages DNS A or SRV records to discover fellow cluster members and can be a good fit for administrators who use Kubernetes or OpenShift to manage their PingFederate containers.
Server metrics
Administrators can optionally enable PingFederate 10 to return detailed server metrics at its heartbeat endpoint. Available information includes system and JVM memory usage, CPU load, various session map sizes, and statistics around response time and response concurrency. This additional knowledge helps administrators understand their PingFederate installations and aids auto-scaling solutions to scale up, out, down, or in, based on server metrics.
Upgrade enhancements
Upgrade tools
The PingFederate Upgrade Utility is now part of the PingFederate product distribution file, located in the upgrade folder. This bundling removes the need for downloading the tool separately.
Migration of various resources
We have also improved the Upgrade Utility to copy the following resource files from the previous installation to the upgraded installation:
  • Message .properties files located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.

    For recognized files, such as the pingfederate-messages.properties file, the upgrade tool merges new changes into them. This copy-and-merge operation also applies to localized versions of the recognized files. The upgrade tool adds new message keys (if any) and their corresponding English messages in the localized copies.

    For unrecognized files, the upgrade tool copies them to the upgraded installation without modifications.

  • Non-default templates located under the <pf_install>/pingfederate/server/default/conf/template directory.
  • Cluster configuration files (cluster-*.conf), size-limits.conf, and wsfed-claims-util.conf located in the <pf_install>/pingfederate/server/default/conf directory.
  • The previous license file if it is still applicable to the current installation.
These improvements apply to upgrades performed by using the PingFederate Windows installer as well.
Maintenance releases via in-place update
We strive to continually improve existing and new functionality of PingFederate by releasing maintenance releases. In the past, administrators can upgrade to the latest maintenance release by using one of the upgrade tools. While this upgrade path remains viable, we are providing a new path to update to the latest maintenance release in version 10. Instead of using one of the upgrade tools to create a new installation based on the previous installation, starting with version 10 an administrator can apply an in-place patch to update a PingFederate installation to the latest maintenance release of the same feature release. This new path vastly overcomes the burden of updating various end-user templates and configuration files that the upgrade tools do not handle when creating a new installation, thus reducing the effort required to keep the current PingFederate up-to-date.
Multiple maintenance releases in a single cluster
PingFederate 10 also supports having multiple versions of its maintenance releases in a single cluster. This flexibility can aid administrators in performing a canary deployment of the latest maintenance release. When used in conjunction with the new in-place update path, keeping a PingFederate cluster up-to-date with the latest maintenance release has never been easier. The Cluster Management screen has also been updated to show the version of PingFederate for each connected node, giving administrators a bird's-eye view of their clustered environments. It is worth mentioning that, depending on how requests are routed during the canary deployment, runtime behaviors may differ from one request to another. We recommend updating all nodes to the same maintenance release in a timely manner, starting with the console node.
Other improvements
  • The administrative API has been extended with the /serverSettings/systemKeys endpoint to manage system keys.
  • PingFederate now records Java garbage collection metrics, which could help administrators to understand their PingFederate installation and memory utilization. jvm-garbage-collection.log files are located in the <pf_install>/pingfederate/log directory.
  • When configuring attribute source and user lookup settings, administrators can specify a static value or the bearer token received from earlier in the authentication flow (like in an OIDC IdP connection) to be used in an Authorization HTTP request header.
  • PingFederate now caches recently invoked externally-stored OAuth clients, thus reducing the number of round trips and improving runtime performance.
  • Updated the following bundled components and third-party dependencies:
    • UnboundID LDAP SDK 4.0.12
    • Jackson Databind
    • JGroups 4.1.6
    • jose4j 0.7.0
    • Log4j2 2.12.1

Resolved issues

Ticket ID Description
PF-24929 Resolved an issue that prevented the processing of encrypted assertions in upgraded installations.
PF-24721 Deleted scopes are removed immediately from the OAuth Scope Selector retrieved through the API.
PF-24522 The HTML Form Adapter default template now conforms to Internet Explorer 11 standards.
PF-24406 Fixed an issue where unreachable datastores caused dependency errors.
PF-24290 The administrative API now behaves correctly when updating OIDC static keys. Previously, the API restricted the choice of certificate based on its signature algorithm.
PF-24112 Resolved an issue where the default Authentication Application is incorrectly invoked in the HTML Form Adapter's 'Trouble Signing On' flow, even when there is no Authentication Application configured in the Authentication Policies.
PF-24010 The Authentication API Explorer now properly masks passwords in logs in some error cases.
PF-23969 When configuring authentication policy sessions, using an integer up to the maximum of 43200 in the Session Revocation Lifetime (Minutes) field no longer causes an integer overflow.
PF-23544 Fixed an issue where TRACE logging in some loggers may cause invalid responses when adapters are processing POST data in some cases.
PF-23533 The default maximum size of the JDBC connection pool has been increased from 8 to 100. The default minimum has been increased from 0 to 10.
PF-23496 IdP connections can now be mapped to policy contracts when SAML is disabled.
PF-21203 Fixed an issue with server.log file rotation where the log would not roll under some scenarios if rotated log files are deleted.