PingFederate Server

PingFederate 12.1 (June 2024)

New features and improvements in PingFederate 12.1.

New features and enhancements

Active and passive administrative consoles

New PF-34962

We’ve added a feature that allows you to create an active admin console and one or more passive backup admin consoles in a clustered environment.

Even though only one node can be active, the passive nodes are always kept in sync, so you can easily promote them to the active console. This reduces downtime in the event of an outage on the node with the active admin console.

Learn more in Active and passive administrative nodes.

Runtime threads bulkheads

New PF-35345

We’ve added the ability to implement runtime thread bulkheads that limit the percentage of threads that can be waiting on external data sources. After the limit is reached, further requests are rejected.

This improves resilience, reliability, and availability by minimizing the impact of a broken data source connection on other connections.

You can configure bulkheads in the com.pingidentity.common.util.resiliency.BulkheadManagerImpl.xml file. You can also configure runtime notifications for bulkhead threshold events.

Learn more in Configuring runtime thread bulkheads.

Decrypting SAML attribute values

New PF-34887

We’ve added a new special attribute, SAML_AUTHN_RESPONSE_ASSERTION, to access the Assertion element of the SAML 2.0 response messages during attribute mapping.

Learn more in Special attribute names in contracts.

Custom key identifier

New PF-34883

We’ve added the ability to define a custom key identifier (KID) for OIDC and OAuth signing and decryption keys for each RSA-based signing algorithm.

Custom KID values help with special environments and custom requirements for RSA-based JSON Web Keys (JWK) published in the JSON Web Keys endpoint.

Learn more in Keys for OAuth and OpenID Connect.

Cookieless authentication API

New PF-34889

We’ve added the ability to enable a redirectless authentication API OAuth flow through the authorization endpoint without cookies.

You can now use the authentication API without having to manage and process cookies. Instead of cookies, the API includes details within the JSON response that need to be included as a simple HTTP header value in responses to PingFederate.

This improvement is especially useful for native app developers and reduces the implications of third-party cookie issues.

Learn more in Configuring OAuth clients.

Resource indicators for OAuth 2.0

New PF-35341

We’ve added support for the resource parameter to allow clients to indicate the protected resources to which it is requesting access.

The resource parameter is available for use during access token mapping.

Learn more in the RFC 8707 specification and Token endpoint.

PingOne Australia region support

New PF-31859

We’ve added support for the Australia region in the PingOne unified admin feature. You can now configure the pf.pingone.admin.url.region property for Australia (.com.au).

The Asia region is deprecated. We recommend using the Australia region instead.

Learn more in Configuring PingFederate properties.

Publish signing keys to JWKS endpoint

New PF-34886

We’ve added the ability to optionally publish asymmetric signing keys configured in a JWT Access Token Management Plugin instance to the PingFederate JWKS endpoint.

Publishing JWKs to the JWKS endpoint reduces the number of required JWKS endpoints, and allows you to use more standard client libraries and fewer custom clients.

Published keys are discoverable using the OpenID Provider configuration endpoint.

Learn more in Configuring an access token management instance.

Publish x5t thumbprint to JWKS endpoint

New PF-35342

PingFederate now publishes the x5t x.509 certificate SHA-1 thumbprint parameter from the JWKS endpoint by default.

Learn more in JSON Web Keys endpoint.

Custom URI schemes for redirect validation

New PF-34891

We’ve added support for custom URI schemes in redirect validation for OAuth and OIDC clients.

You can now allow redirects to URIs such as native applications or APIs outside of the HTTP/HTTPS scheme. Because application URIs are often company or brand-specific, this feature reduces the potential for naming collisions with other apps on the same device.

Learn more in Configuring redirect validation.

JARM support for IdP connections

New PF-34884

We’ve added support for JWT Authorization Response Mode (JARM) to identity provider (IdP) connections.

PingFederate already supports JARM in its role as a relying party (RP), and now supports it in its role as an OpenID provider (OP). Instead of having to receive an issued authorization_code and state parameter as a query component, your connection can process a JWT instead.

Learn more in Creating an OpenID Connect IdP connection.

Configure Refresh Rolling Token Interval in hours, minutes, or seconds

New PF-34885

We’ve added a feature allowing you to configure the interval of rolling OAuth tokens in hours, minutes, or seconds.

Learn more in Configuring OAuth clients, Configuring authorization server settings, and Managing client configuration defaults.

New PF-34422

We’ve added support for the PingFederate Magic Link Integration Kit.

Learn more in the Magic Link Integration Kit documentation.

Configurable LDAP health check timeout

New PF-35012

We’ve added the ability to configure the timeout duration for LDAP health checks.

You can configure this option in the ~/server/default/data/config-store/com.pingidentity.common.util.ldap.LDAPUtil.xml file using the HealthCheckResponseTimeoutMillis parameter.

The default value is 2000.

LDAPv3 with StartTLS command

New PF-35349

PingFederate now supports LDAPv3 with the StartTLS command to secure LDAP connections to a directory server.

This feature allows LDAP connections to be initiated on a non-SSL port (such as 389), and then be upgraded to SSL on the same port. This reduces the number of ports that potentially have to be opened within a firewall.

Learn more in Configuring an LDAP connection.

OpenID Connect offline_access scope

New PF-35346

PingFederate now supports the OpenID Connect (OIDC) offline_access scope.

You can now configure OAuth and OIDC clients to receive only a refresh_token when this scope is requested. You can also optionally configure a resource owner consent as required.

Learn more in Configuring authorization server settings and OAuth Client Management Service.

OpenID Connect user registration

New PF-35347

PingFederate now supports user registration through OIDC 1.0 using the prompt=create command.

Including this parameter initiates a user registration flow within the context of OIDC, which reduces developer efforts by eliminating the need for a separate customer registration flow.

Learn more in Configuring request parameters and SSO URLs.

Exposed pi.sri to SDK and attribute mapping

New PF-35453

We’ve added the IN_PARAMETER_NAME_SRI parameter to the SDK, which contains the current pi.sri.

We’ve also exposed the pi.sri value in the Context type for most attribute mappings.

SDK capability for adapters to terminate sessions

New PF-34464

We’ve added a new SessionManager class in the SDK to allow for revoking all sessions or all but the current session.

This works similarly to the Revoke sessions after password change or reset option in the HTML Form Adapter.

PingDirectory log tracking ID

New PF-34338

We’ve added support for the log tracking ID feature in PingDirectory 10.0. PingFederate can use this tracking ID as a transactionId value.

Learn more in Security audit logging.

Improved logging for adapters manager

Improved PF-35079

We’ve improved logging capabilities to associate an adapter ID with adapters that fail to load. This makes misconfigured adapters easier to trace.

OAuth scope reference UI improvements

Improved PF-34952

We’ve added a pop-up modal to several OAuth scope reference pages to improve the scope management user interface.

Learn more in Configuring scope constraints.

Scope management user interface enhancement

Improved PF-34890

We’ve improved the user interface for the Scope Management page, including pagination, a search feature, and new tabs for managing common and exclusive scope groups.

Learn more in Defining scopes.

New connection pool metrics in heartbeat endpoint

Improved PF-34892

We’ve added new connection pool metrics to the heartbeat endpoint and JMX MBeans for Java Database Connectivity (JDBC) and LDAP connections.

New metrics include maximum connection pool size, minimum connection pool size, number of active connections, and number of idle connections.

There is no active connections metric for LDAP connectors, because LDAPConnectionPool does not track the number of connections that are established and currently in use.

Learn more in Customizing the heartbeat message and Liveliness and responsiveness.

Refresh grants revocation and issuance

Improved PF-35527

Refresh grants are no longer revoked when issuance criteria fail.

Also, new grants or access tokens are not issued due to the failure of issuance criteria.

This is the new default behavior for refresh grants.

PingOne MFA Integration Kit

Improved PF-35325

The PingOne MFA Integration Kit has been updated to version 2.3.1.

Aurora PostgreSQL

Improved PF-35383

PingFederate now supports Aurora PostgreSQL version 16.2.

PostgreSQL

Improved PF-35384

PingFederate now supports PostgreSQL version 16.2.

PingDS support

Info PF-34434

We’ve added support for PingDS (formerly ForgeRock DS) datastore.

Learn more in System requirements.

Jetty library upgrade

Improved PF-34039

We’ve upgraded Jetty to version 10.

FAPI and FAPI CIBA certification

Info PF-34897

PingFederate 12.1 is certified for FAPI OpenID Providers (OP) and Profiles, and FAPI CIBA OpenID Providers and Profiles.

Resolved issues

Admin console OIDC login failure

Fixed PF-34523

We’ve fixed an issue that caused PingFederate’s OIDC admin console login to fail when the node.group.id value didn’t match an existing node id.

PingDirectory user attribute queries

Fixed PF-34333

We’ve fixed an issue that caused PingFederate to query all attributes for PingDirectory users, rather than just the required attributes.

DPoP token rejection

Fixed PF-35082

We’ve fixed a defect that caused access token requests to fail due to OAuth 2.0 Demonstrating Proof of Possession (DPoP) proof validation failure when reusing existing persistent access grant is enabled for confidential claims.

License expiration date discrepancy

Fixed PF-35114

We’ve fixed an issue that caused PingFederate to display the expiration date of a PingFederate license in terms of the browser time zone rather than the server time zone.

Web token processing slowdown

Fixed PF-35272

We’ve fixed an issue that caused significant slowdown when PingFederate processed an unencrypted JSON web token (JWT) using JSON web encryption (JWE) deobfuscation.

REST API datastore unable to handle malformed cookies

Fixed PF-35352

We’ve fixed a defect that caused the PingFederate REST API datastore to pass malformed cookies into datastore request headers.

OAuth client in-use detection

Fixed PF-35744

We’ve fixed a defect where client in-use detection caused an IndexOutOfBoundsException when a custom solution is used for client storage.

ClientManagerDynamoDBImpl changes not implemented

Fixed PF-35753

We’ve fixed a defect that caused changes in ClientManagerDynamoDBImpl not to apply when performing a bulk import or using the configuration store API unless you restarted PingFederate.

License issue dates

Fixed PF-35075

We’ve fixed a defect that caused PingFederate to ignore valid license files if they were issued prior to the current license file.

Known issues and limitations

Issue PF-35772

Due to multiple vendors' recent browser versions that block third-party cookies, you might experience issues related to single logout with OIDC (via Front-Channel) and WS-Federation.

Refer to browsers' documentation regarding third-party cookie management to unblock them, if feasible.

Replication notification when switching passive admin console to active

Issue PF-35642

When you switch a passive console to active, PingFederate might display a notification that the configuration has not been replicated, even though the configuration is up-to-date.

Passive admin console UI refresh

Issue PF-35643

When you promote a passive admin console to active, the UI doesn’t refresh until you perform an action.

Multiple active admin consoles

Issue PF-35439

When you make configuration changes on the active console (especially large configuration changes like bulk imports or data archive imports), then promote a passive console to active, it can cause multiple consoles to be active at once. This can result in inconsistent configurations.

Learn how to resolve this issue in Resolving multiple active administrative nodes.

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.

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

  • CloudHSM is 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 logout (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.

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.

Deprecated features

authorizationDetails field deprecation

Info PF-34682

The authorizationDetails JSON field returned by the OAuth consent management endpoint has been deprecated in favor of the new authorizationDetail and authorizationDetailDescription fields.

Learn more about the consent management endpoint in OAuth Consent Management Service.