PingFederate Server

PingFederate 11.3 (June 2023)

New features and improvements in PingFederate 11.3.

New features and improvements

Support for nbf and iat claims in JWT access token managers

New

Now you can configure access token managers to include the JSON web token (JWT) access_token claims nbf (not before) and iat (issued at). This enables stronger validations by receiving clients or protected resources that process that access_token. For more information, go to Configuring an access token management instance, and in the JSON web token data model section click the JSON token management tab.

Retries for client-side LDAP errors

New

To further improve reliability and robustness, now PingFederate executes retries rather than failover only. PingFederate initiates a single retry if a request fails and it appears the connection has become invalid. For more information, see the Retry Failed Operations field in Setting advanced LDAP options.

Referencing incoming PAR parameters in authentication policies

New

For authorization requests, parameters can now be referenced for incoming PAR requests (pushed authorization requests) inside authentication policies. This lets PingFederate process incoming requests independently of how it received them. For more information, see Pushed authorization requests endpoint.

Unique identifiers for PingFederate transactions

New

To improve logging, PingFederate now uses a transactionId. For each transaction, this value won’t change between the initial request and the final response. This is especially useful for troubleshooting. For more information, see the transactionid field in Security audit logging.

All user attributes available to HTML and mail templates

New

Now you can configure HTML and mail templates with user details. With these details, you can personalize user facing pages and include messages, such as greetings by name, or email addresses that were used for a password recovery flow. The attributes are documented in the templates.

Logging certificate expiration advance warnings

New

Previously, PingFederate produced notifications to inform administrators about expiring certificates. Now you can configure PingFederate to log upcoming expirations without producing notifications. For more information, see Configuring runtime notifications.

Improved European Union compliance with SAML 2.0

New

Two major SAML 2.0 messaging improvements align PingFederate closer to EU regulations:

  • Now PingFederate can decrypt EncryptedID elements included as SAML attributes. They no longer must be enclosed as an EncryptedAttribute. For more information, see Specifying XML encryption policy (for SAML 2.0).

  • To enhance signing capabilities, PingFederate now also supports some of the RSASSA-PSS algorithms. For more information, see Signing algorithms.

Support for credential-protected forward proxy servers

New

Because proxy servers can require credentials for authentication purposes, now you can configure PingFederate with proxy server credentials so that connections can be easily established and secured. For more information, see Configuring forward proxy server settings.

Amazon DynamoDB for attribute source lookups

New

Our continued effort to support Amazon DynamoDB (NoSQL) now lets you use DynamoDB as a source for attribute lookups. The connector supports the DynamoDB query language so you can easily configure it. For more information, see Configuring an AWS DynamoDB datastore.

OAuth 2.0 DPoP

New

As regulations for APIs in the context of financial services tighten, it’s important to support highly secure API authentication and authorization methods. OAuth DPoP (Demonstrating Proof-of-Possession) is an extension to the OAuth framework and specifies how OAuth tokens are bound to clients. Clients must digitally prove the ownership of these tokens at runtime, which prevents unauthorized clients from misusing them. This extension is useful for any OAuth scenario, not only in financial environments. For more information, see Configuring authorization server settings.

Logging the TLS version that clients use

New

For TLS connections, PingFederate can now log the TLS version that clients use. This gives you an easy way to identify clients that might need updates to use newer versions. For more information, see the tlsversion field in Security audit logging.

Certificate expiration dates added to certificate menus

New

In the administrative console, now certificate selection menus show the distinguished name (DN) and expiration date for each certificate, rather than a serial number. This gives you easy access to relevant information.

New JWT Token Processor

New

A new JWT token processor enhances the token exchange capabilities so that you can leverage any configured issuer. Now PingFederate can validate and accept incoming tokens that were created by pre-configured issuers. For more information, see Configuring a JWT Token Processor 2.0 instance.

Enhanced authentication policies

New

Complex authentication policies are sometimes challenging to manage. To simplify your work and add flexibility to policies, PingFederate provides several policy enhancements:

PAR support for OIDC IdP connections and OIDC admin authentication

New

PingFederate now initiates outbound authorization requests using the PAR endpoint of the target authorization server if you expose it. This enhancement lets PingFederate use PAR inbound and outbound, which improves OAuth flow security. For more information, see the Pushed Authorization Request Endpoint field in Configuring OpenID Provider information.

Support for OpenID Connect back-channel logout

New

In the context of OpenID session management, PingFederate now supports back-channel logout. PingFederate supports this feature whether it’s configured as an OpenID Connect provider (OP) or a relying party (RP). For more information, see the OpenID Connect Back-Channel Logout 1.0 specification.

Ability to include x5t and typ in ID token headers

New

Now PingFederate can include JWT header values x5t and typ in the ID tokens it issues. You can include the x5t header with static keys enabled, whereas you can configure the typ header to an appropriate value without a dependency on the types of keys. The x5t header adds another mechanism for verifying the validity of a received JWT. For information about the x5t and typ parameters, see the JSON web key (JWK) and JWT specifications, respectively, and steps 9 and 10 in Configuring policy and ID token settings.

Support for the alg parameter response for JWKS keys

New

The alg header is now supported in PingFederate’s JWKS endpoint. Any elliptic curve keys and all RSA-256 based keys expose this header. This feature lets clients verify that a received JWT has been signed by the advertised algorithm. For information about the alg parameter, see the JWK specification and JSON Web Keys endpoint.

Support for client_secret_jwt as client authentication

New

With the client_secret_jwt authentication method, a client can choose to create a signed JWT when authenticating against PingFederate’s token endpoint, introspection endpoint, PAR endpoint, or CIBA endpoint instead of providing the client secret. This feature prevents potential client secret leakage because it’s not actively exchanged with any party. PingFederate also supports this feature when it acts as an RP. For more information, see client_secret_jwt in the Open ID Connect specification and Client authentication schemes.

Refresh token reuse and revocation best practice

New

PingFederate now revokes a chain of tokens if a refresh token is revoked or if a refresh token is reused. This includes derived authorization codes and access tokens. For more information, see the Refresh Token settings section of Configuring authorization server settings.

Overriding configuration settings using environment variables

New

Now you can configure many properties as environment variables instead of setting them in properties files. This is especially important for container environments, which is common practice.

Auditing enhancements

New

Several enhancements provide more details in PingFederate generated logs. These include the logging of JWT IDs (jti), hashed values of authorization codes, access tokens, and refresh tokens. Also, PingFederate now logs which system has locked out users after multiple, unsuccessful login attempts, so you’ll know if it was PingFederate or an LDAP server. PingFederate also adds more details to the administrative API logs, so now there are almost no differences between logs generated when using the administrative console or administrative API. For more information, see Administrator audit logging, Administrative API audit log, and Security audit logging.

Amazon DynamoDB and OAuth client records

New

Now you can manage OAuth clients in Amazon DynamoDB. With this update, you can use DynamoDB to manage OAuth clients, persistent grants, and persistent authorization sessions. For more information, see Configuring an Amazon DynamoDB for client storage.

Upgraded Velocity Engine 2.3

New

PingFederate now supports Apache Velocity Engine 2.3. For more information, see Upgrading in the Apache Velocity Engine documentation.

Support for strict content security policy (CSP) for HTML templates

New

Now you can include CSP policies for HTML templates without having to implement workarounds. For more information, see Customizable user-facing pages.

Ability to use additional Velocity tools

New

Now you can use Velocity templates with more tools, such as cookieTool.

Support for Microsoft Azure SQL Managed Instance

New

PingFederate now supports Microsoft Azure SQL Managed Instance. For more information, see the Datastore integration table in System requirements, and for more information on how to configure a connection to Microsoft Azure SQL Managed Instance, see Configuring a JDBC connection.

mTLS authentication for REST API datastores

New

PingFederate now supports mutual TLS (mTLS) client authentication for REST API datastores.

mTLS authentication for LDAP datastores

New

PingFederate now supports mTLS client authentication for LDAP datastores.

Entrust nShield Connect HSM and Java 11

New

Now when you integrate an Entrust nShield hardware security module (HSM) with PingFederate, you can use Java 11.

Bundled User Count Utility

New

We added the User Count Utility (UCU) as a bundled component. You can use the UCU to produce unique and active user counts in a PingFederate environment.

Upgraded third-party components

New

We upgraded the following third-party components:

  • Upgraded Spring Framework to 5.3.27

  • Upgraded jose4j to 0.9.3

Resolved issues

SAML login session tracking

Fixed PF-33168

We improved SP-Initiated SAML login session tracking. This security improvement can affect existing SAML SP connections that rely on multiple session states in a single transaction.

For more information about how your configuration can be affected, and the steps to resolve issues, see Solicited SAML Response Validation in the Ping Identity Support Portal.

Log message when multiple entries match the LDAP PCV search filter

Fixed PF-32427

Now when multiple entries match the LDAP PCV search filter, the following message appears in the log at DEBUG level: error code 4 - This search operation has sent the maximum of 1 entries to the client

Multivalued authorization request parameters

Fixed PF-32783

Now multivalued request parameters work as expected in authorization requests for OIDC administrative console authentication.

Tracked parameters in the LDAP search filter when using the administrative API

Fixed PF-32914

Now you can use tracked parameters in the Attribute Sources and User Lookup LDAP search filter when using the administrative API.

Showing and hiding passwords being entered

Fixed PF-33059

Now all password entry fields in PingFederate templates have icons that let users show and hide the password they’re entering.

Connections and OAuth clients referencing deleted extended properties

Fixed PF-33311

When a connection or OAuth client references a deleted extended property, PingFederate no longer throws a null pointer exception. Instead it ignores the extended property and logs an error.

Fixed PF-33151

Now PingFederate can use customized messages from external consent adapters in error responses.

Restricting password credential validators

Fixed PF-33487

When restrictToDefaultAccessTokenManager is enabled on an OAuth client, the client can only get access tokens when being validated by password credential validators that are mapped to the restricted access token manager.

Bypass Authorization Approval and prompt parameters

Fixed PF-33598

When an OAuth client has Bypass Authorization Approval enabled, now that setting takes precedence over the prompt parameter in requests.

Document file permissions

Fixed PF-33605

Updated the file permissions of legal documents.

The memoryoptions script allocates excessive JVM heap

Fixed PF-33610

The memoryoptions script no longer allocates excessive JVM heap on Windows systems.

Authorization Code and Device Authorization grant handling

Fixed PF-33622

For the Device Authorization grant type, if Check Activation Code is set to Before Authentication, then authorization detail is set in the input parameters map when IdpAuthenticationAdapterV2 in the SDK is invoked.

Converting the values of binary attributes from PingOne LDAP gateway datastores

Fixed PF-33637

Now when PingFederate retrieves a binary attribute from a PingOne LDAP gateway datastore, it correctly converts the attribute value to the specified format (base64, SID, hex).

Unexpected certificate usage

Fixed PF-33709

When more than one trusted CA matches the issuer DN of an OAuth client, now PingFederate only flags the trusted CA as in use if its certificate hasn’t expired and its subject DN matches the client’s configured issuer DN.

Potential information disclosure vulnerability

Fixed PF-33867

Removed a potential information disclosure vulnerability.

Jetty unable to serve gzip precompressed resources

Fixed PF-33869

Now PingFederate allows Jetty to precompress resources such as images and CSS.

Returning 400 error instead of a 500 error

Fixed PF-30236

When a system-level issue causes a data source attribute lookup to fail during OAuth flows, if the <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.saml20.domain.AttributeMapping.xml file’s AbortOnAttrLookupFailure attribute is set to true, now PingFederate returns a 500 error instead of a 400 error.

Usercount Utility’s aggregate command

Fixed PF-32757

When you run the Usercount Utility’s aggregate command:

  • If all .ucu files contain tracking IDs, the utility generates a user count for each event, like before.

  • If no .ucu files contain tracking IDs, now the utility generates a user count for each application.

  • If some .ucu files contain tracking ids but others don’t:

    • for the files without tracking IDs, now the utility generates a user count for each application.

    • for the files with tracking IDs, now the utility generates a user count for each event.

CPU load displayed as N/A

Fixed PF-32837

Now when the CPU load is 0, heartbeat pages display the value with digits instead of as “N/A”.

Unexpected carriage return in audit logs

Fixed PF-32989

We resolved an issue that caused an unexpected carriage return in audit logs during SP-initiated single sign-on (SSO) if an identity provider responded with a non-success status.

Known issues and limitations

PingID password credential validator with integrated RADIUS server

Issue

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

Issue

  • Although PingFederate 11.3 and later support DPoP, a known limitation is that the following features don’t support DPoP when PingFederate is the RP:

    • The administrative console authentication scheme using OIDC

    • The administrative API authentication scheme using OAuth 2.0

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

  • When using mTLS authentication to authenticate to an LDAP server for administrative console or administrative API access, PingFederate doesn’t support using a Microsoft Active Directory server.

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

PingOne MFA CIBA Authenticator

Issue PingOne MFA

PingFederate 11.3 is not compatible with the PingOne MFA CIBA Authenticator bundled in PingOne MFA Integration Kit version 2.1 and earlier. This issue was resolved in version 2.2 of that integration kit.

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 an 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 on Windows. 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.

HSMs

Issue

AWS CloudHSM

  • 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 EC certificate as an SSL server certificate.

  • TLS 1.3 is not currently supported.

Entrust 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 import a PKCS12- or PEM-formatted EC certificate.

  • It is not possible to use an EC certificate as an SSL server certificate.

  • TLS 1.3 is not currently supported.

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.

Session revocation API

Issue PPQ-33519

POST requests to the Session Revocation API do not support the Private Key JWT authentication type.

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.

Amazon SNS Notification Publisher

Issue

When deploying PingFederate with a forward proxy, plugins based on the AWS SDK, such as the Amazon SNS Notification Publisher, will only honor the http.proxyHost, http.proxyPort, http.proxyUser, and http.proxyPassword properties in run.properties. The plugin will rely on these properties even if the service URL is https.

PingOne Fraud integration kit

Info PingOne Fraud

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

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 (www.oracle.com/middleware/technologies/unified-directory.html) and other supported directory servers. For a full list, see System requirements.

SNMP

Info

Starting with PingFederate 10.2, monitoring and reporting through the 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.