PingFederate Server

PingFederate 11.1 (June 2022)

New features and improvements in PingFederate 11.1.

New features and enhancements

PingOne integration

New PingOne

We’ve added Kerberos authentication via PingOne and the PingOne LDAP Gateway Data Store. This new capability allows PingFederate in the cloud, without a direct connection to Active Directory, to complete Kerberos authentication for browser-based SSO requests and STS transactions through PingOne.

JWT Secured Authorization Response Mode (JARM)

New

We’re proud to support JWT Secured Authorization Response Mode (JARM) in version 11.1. JARM allows authorization servers to transmit authorization responses in JSON web tokens (JWTs), providing digital signature and encryption, sender authentication, and audience restriction. As JARM becomes a requirement in FAPI 2, you can deploy open banking solutions confidently.

JWT Response for OAuth Token Introspection

New

We’re also introducing support for JWT Response for OAuth Token Introspection, a draft specification on track to become one of the authorization server requirements in the FAPI 2 Advanced Profile. JWT-secured introspection responses provide stronger assurance to the introspection requesters, most relevant when the requester, such as a resource server, expects to receive verified claims from the authorization server.

Client secret management

New

Seamless client secret rotation no longer requires real-time coordination between PingFederate administrators and the application development teams. You can now configure PingFederate to retain previous secrets for a configurable period, during which the application teams can work on updating the client secrets in their apps. This enhancement drastically lowers the costs of securing applications that use client secrets for authentication. For more information, see "Client Secret Retention Period" in the topic Managing client configuration defaults.

API support for Device Authorization Grant

New

In addition to template-driven user experience, the user authorization step from Device Authorization Grant supports API now. You can also decide whether PingFederate should check the device activation code before or after authentication. These new capabilities enable you to build applications with the desired user experience for input-constrained devices, such as smart TVs or telepresence equipment.

Amazon DynamoDB for grants

New

You can store OAuth persistent grants in Amazon DynamoDB, which allows you to take advantage of a NoSQL database where it matters most: delivering responsive experiences to globally distributed users and offering high availability at ease.

Revocation of self-contained access tokens

New

You can optionally enable direct revocation for self-contained access tokens (JWT access tokens). This flexibility provides a secure way to invalidate access tokens without revoking the underlying refresh tokens or persistent grants. For more information, see Configuring an access token management instance and its description of the Enable Token Revocation checkbox.

A new alert system

New

PingFederate 11.1 centralizes alerts, such as the reminder to replicate configuration, under the new bell icon in the top menu. You can review important alerts from any configuration window.

the bell icon displays important alerts

Copy-and-paste authentication policies and fragments

New

Previously, if you wanted to update an authentication policy or a reusable policy fragment midstream, they had to reconfigure all downstream paths, which can take some effort. With PingFederate 11.1, you can copy a subtree of policy paths before removing a step (such as an IdP adapter), adding a new step (such as a selector or another IdP adapter), and then pasting the subtree back to the policy. This new capability applies to reusable policy fragments and between authentication policies and reusable policy fragments.

Administrative API to move individual policies

New

You can use the administrative API to move an individual policy to a specific location. This enhancement makes re-organizing policies by API requests easier and safer.

Cluster configuration management

New

PingFederate engine nodes now capture common configuration replication issues in their server logs and send replication status back to the console node. The Cluster Management window provides live updates when you select Replicate Configuration in the Cluster Management window. If an error occurs, you can act on it immediately and recover from potential outages faster.

Passthrough IdP Adapter

New

You can now associate authentication sessions with user identities passed through the new Passthrough Identity Provider (IdP) Adapter. By placing the Passthrough IdP Adapter downstream from an IdP connection in a policy tree, you can take advantage of additional capabilities associated with defining a user key. For example, you can use the user key to query or revoke a user’s authentication sessions.

Kerberos authentication and ObjectSID

New

The Kerberos Adapter and the Kerberos Token Processor now return the ObjectSID attribute value. Because ObjectSID uniquely identifies the user in Active Directory, leveraging it helps streamline the Attribute Source & Lookup configuration.

Kerberos authentication and re-authentication

New

You can configure the Kerberos Adapter to fail when the service provider asks for re-authentication by including ForceAuthn=true (SAML 2.0) or prompt=login (OpenID Connect) in their authentication requests. For example, suppose user interactions are required when the partners ask for re-authentication. In that case, you can add the HTML Form Adapter to the Fail policy path of the Kerberos Adapter.

More error handling options

New

  • You now can configure individual authentication policies to handle authentication failures locally without redirecting to the service providers or returning error messages to the OAuth clients. This flexibility addresses the scenario where an IdP-oriented end-user experience is desirable.

  • PingFederate now includes error results from issuance criteria in error responses. Partners can use the error results to resolve issues as needed. If the invoked policy is configured to handle failures locally, you can do the same to improve the end-user experience.

  • You can now optionally configure the HTML Form Adapter not to return control to PingFederate when an account lockout occurs. Instead, PingFederate returns a “please try again later” message to the browser or the authentication API application.

Extended properties for end-user interactions

New

You can now leverage extended properties in Velocity templates when customizing template-driven end-user interactions. You can reference extended properties in the templates instead of creating multiple If/ElseIf/Else directives, significantly reducing the initial effort. New and updated experiences can be inherited from extended property values from the OAuth client records and Browser SSO connections, eliminating most of the maintenance costs. PingFederate also passes extended property values to authentication API applications. As a result, application developers who create and maintain end-user UX for customer identities will benefit from this new enhancement.

Better documentation in Velocity templates

New

We’ve also improved inline documentation in our Velocity templates. Moving forward, we will maintain variable names and their definitions consistently to communicate changes, such as introducing new variables.

Enhancements in Thales HSM integration

New

Both Java 11 and 8 environments are supported when integrating with Thales Luna Cloud Hardware Security Module (HSM) Services or Luna Network HSMs. For more information about Thales Luna HSM Client, see the Luna Cloud HSM Service Client Guide and Luna Network HSM Documentation Archive.

Secondary signing certificate

New

You can now add a secondary signing certificate to your connections. If configured, PingFederate includes it in both the metadata exports and the metadata URL responses. This flexibility allows you to notify your partners about upcoming changes more easily through metadata.

Administrative API improvements

New

We improved the PingFederate administrative API to manage the following configurations:

  • JIT provisioning settings in IdP connections

  • System > Data & Credential Stores > Identity Store Provisioners

  • System > Server > General Settings

  • System > Server > WS-Trust Settings

Other improvements

New

  • We significantly improved our metrics exposed through HTTP (at the heartbeat endpoint) and JMX to help you detect and diagnose performance issues. Both channels include HTTP response code counts, data source response time statistics, and Jetty queue size information; these metrics help troubleshoot latency issues associated with datastores or traffic volume.

  • PingFederate now uses OCSP to obtain certificate revocation status by default on new installations. As part of this enhancement, PingFederate uses the OCSP responder URL provided in the certificate first, followed by the now optional Default OCSP Responder URL, and lastly, CRL, making the certificate validation process more efficient.

  • The administrative console now provides guidance when you attempt to import a configuration archive obtained from a different version of PingFederate.

  • PingFederate 11.1 supports Amazon IAM roles for service accounts, which increases security posture with credential isolation and auditability.

  • PingOne Verify is now part of the PingFederate distribution .zip file and Windows installer.

  • We also updated the following bundled components and third-party dependencies:

    • PingID Integration Kit 2.17

    • PingOne Fraud Integration Kit 1.0

    • PingOne Protect Integration Kit 1.2

    • Jackson-Databind 2.12.7

    • Log4j2 2.17.2

    • Spring Framework 5.3.20

Resolved Issues

H2 database engine upgrade

Fixed PF-21198

Upgraded the H2 database engine to version 2.1.210.

A username in the URL during change password flows

Fixed PF-24501

The username no longer appears in the URL during change password flows.

Guava upgrade

Fixed PF-28932

Upgraded the Guava dependency to version 30.1.1.

OAuth client Issuer DN

Fixed PF-29368

If the administrative API was used to create an OAuth client that has the Client Certificate authentication type, and the client’s Issuer DN does not have a normalized DN value, the administrative console’s Client window no longer fails to show the Issuer DN as the default value. This issue didn’t affect runtime behavior.

Time stamp for last update

Fixed PF-29761

When a user record in a datastore mistakenly has a future date for the last update time, PingFederate no longer uses that date as the value of attrib_last_timestamp in the channel_variable table. Instead, PingFederate sets the value to the maximum time stamp that is not in the future.

Number and Boolean data types in JSON responses from REST API data source lookups

Fixed PF-29835

The JSON response from REST API data source lookups now retains number and Boolean data types instead of converting them to strings.

NotYetConnectedException warning messages from JGroup in the server.log

Fixed PF-30075

Resolved an issue that caused the NotYetConnectedException warning message to repeatedly appear in the server.log when using AWS_PING for dynamic cluster discovery.

Matching OAuth client’s redirection URIs

Fixed PF-30146

If the OAuth client’s redirection URI contains a wild card in the authority part of the URI, and the redirect_uri parameter of the token request contains userinfo in the authority part, then PingFederate will no longer consider the redirection URI a match.

Potential security vulnerability

Fixed PF-30255

Resolved a potential security vulnerability.

Logging invalid assertion errors

Fixed PF-30495

In a specific case, when PingFederate logs an invalid assertion error, the error message no longer fails to include a remark about why the assertion or response is invalid.

Null pointer exception in authentication API password reset flow

Fixed PF-30558

When an OAuth client is performing a password reset through the authentication API, if PingFederate does not find any session attributes, now PingFederate logs an error state instead of a null pointer exception.

Determining authentication instants for flows

Fixed PF-30770

Resolved an issue that prevented PingFederate from correctly determining the authentication instant for the flow when the initial OIDC authorization request specifies a max_age, the flow falls through to legacy authentication source selection (policies are disabled or no policy applies), and the user chooses an upstream OIDC IdP connection.

Templates for PingOne MFA 1.6.1

Fixed PF-30806 PingOne MFA

PingFederate now includes all the templates for PingOne MFA 1.6.1.

Dependency errors for SAML token processors and generators

Fixed PF-31054

When saving SAML token processors or generators, PingFederate now correctly handles dependency errors caused by misconfigured settings on the Protocol Settings window’s Federation Info tab.

Preserving the order of map type configurations

Fixed PF-31145

Now PingFederate preserves the order of map type configurations under <pf_install>/pingfederate/server/default/data/config-store when performing a bulk export or a GET operation at the /configStore administrative API endpoint.

Warning about using the administrative console in multiple tabs

Fixed PF-31280

Now if you use the PingFederate administrative console in multiple tabs on one browser, it warns you that doing so might cause inconsistent behavior which could corrupt its configuration.

Saving authorization server settings overwrites scope.whitelist

Fixed PF-31304

Resolved an issue that caused PingFederate to overwrite the scope.whitelist in the \data\config-store\org.sourceid.oauth20.domain.AuthzServerManagerImpl.xml file when you save the authorization server settings.

OAuth client IDs added to admin.log entries

Fixed PF-31561

Now OAuth client MODIFY, CREATE, and DELETE event log entries in the admin.log include the client ID.

Honoring the property for maximum HTTP request body size

Fixed PF-31575

Now PingFederate honors the value of http.maxRequestBodySize in the run.properties file, which specifies the maximum HTTP request body size of any incoming request to PingFederate’s web services and administrative API.

Known issues and limitations

Administrative console and administrative API

Issue

  • /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.

TLSv1.3

Issue

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 run.properties file:

  • pf.tls.client.protocols

  • pf.tls.runtime.server.protocols

  • pf.tls.admin.server.protocols

TLS cipher suite customization

Issue

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.

Java

Issue

  • 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 (HSM)

Issue

  • For Entrust HSMs, it is not possible to use an elliptic curve (EC) certificate as an SSL server certificate.

  • For Entrust HSMs, PingFederate must be deployed with Oracle Server JRE 8 or Amazon Corretto 8.

  • For keys stored in AWS CloudHSMs, JWT token signing fails when using RSASSA-PSS SHA-512.

  • For keys stored in Thales HSMs, JWT token decryption fails when using RSAES OAEP with AES-CBC-192 or AES-CBC-256. This issue only arises if PingFederate is configured with static OAuth and OpenID Connect keys and is consuming a token encrypted with one of these keys.

  • When PingFederate is configured in hybrid mode with a Thales HSM, it is not possible to export a locally-stored EC key pair.

  • When PingFederate is configured in hybrid mode with a Thales HSM, 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 locally, and PingFederate is consuming a token encrypted with this key.

  • TLS 1.3 is not currently supported with any HSM.

SSO and SLO

Issue

  • 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

Issue

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

Issue

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

OAuth

Issue

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

Issue

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.

Provisioning

Issue

  • 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.

Logging

Issue

  • 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

Issue

  • 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.

RADIUS NAS-IP-Address

Issue

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.

Deprecated features

Microsoft Internet Explorer 11

Info

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

Info

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

Oracle Directory Server Enterprise Edition

Info

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.

SNMP

Info

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

Roles and protocols

Info

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

Info

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

Info

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.