PingFederate 12.0 (December 2023) - PingFederate - 12.0

PingFederate Server

bundle
pingfederate-120
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 12.0 (Latest)
category
Administrator
Administratorguide
Audience
Capability
ContentType
DeploymentMethod
Guide
Product
Productdocumentation
SingleSignonSSO
Software
SystemAdministrator
pf-120
pingfederate
ContentType_ce
Guide > Administrator Guide
Guide
Product documentation

New features and improvements in PingFederate 12.0.

New features and enhancements

Support for RP-initiated logout

NewPF-34418

OpenID Connect (OIDC) relying party (RP) initiated logout allows OAuth clients to request that the OpenID Provider (OP) perform a federated logout. PingFederate now supports this standard, both when PingFederate acts as the OP as well as when it acts as the RP via an OIDC IdP connection.

For more information, see OAuth Client Management Service, Configuring OpenID Provider information, and OpenID Connect RP-initiated logout endpoint.

Add risk provider to Identifier First Adapter

NewPF-34415

You can now add risk provider such as CAPTCHA to Identifier First adapters.

For more information, see Configuring an Identifier First Adapter instance

Skip redirect to authentication application if no action is required

NewPF-34413

API-capable IdP adapters can now prevent a redirect to the authentication application if no user interaction is required.

For more information, see Upgrade considerations.

Alert and report when approaching maxThreads

NewPF-34437

You can now configure runtime notifications to alert you when the number of threads in use exceeds a set threshold. You can also use this feature to initiate and log a thread dump event.

For more information, see Configuring runtime notifications.

Persist consent decision when revoking refresh_token

NewPF-33318

You can now configure your authorization server settings for OAuth and OIDC users so that their decisions to grant access can be persisted after a refresh_token is revoked.

For more information, see Authorization Consent in Configuring authorization server settings.

Admin console notification of expiring certificates

NewPF-34428

PingFederate will now issue a notification in the admin console before a certificate expires. You can configure the duration of the notification before and after expiry in the Runtime Notifications menu.

Deleted certificates are removed from the notifications menu.

For more information, see Configuring runtime notifications.

Selective replication for connections and OAuth clients

NewPF-33989

We further improved support for self-service and application on-boarding use cases. OAuth applications and SAML connections can now be replicated to PingFederate engine nodes without affecting any dependencies. This enhancement lets development teams manage their applications without the help of PingFederate administrators. For more information, see Cluster management.

OpenID Connect Front-Channel Logout support

NewPF-33986

Continuing the PingFederate tradition of recognizing open identity standards, it now supports the OpenID Connect Front-Channel Logout specification. This feature enables global sign-off user journeys. It's available in addition to PingFederate’s proprietary front-channel logout protocol. For more information, see Configuring OAuth clients.

Log category to capture details of protocol requests and responses

NewPF-33987

For OpenID Connect IDP connections, log files now include more details so that you can analyze and resolve connection problems easier. You can enable this feature just by selecting a check box in the Log Settings. For more information, see Log settings.

Creating short-lived or non-persistent sessions when This is my device isn't selected

NewPF-33982

Now you can configure PingFederate to enable sessions on shared devices. Devices can be configured as private or public (unspecified) and maintain persistent sessions. This feature is available through the HTML Form Adapter. For more information, see Configuring authentication sessions.

The CyberArk Secret Manager can pull different username values from CyberArk

NewPF-33985

The integration with the CyberArk Secret Manager now allows access to all values available through the CyberArk interface. This gives you more freedom when building user journeys. For more information, see Configuring instances of the secret manager plugin for the CyberArk Credential Provider.

Password reset email OTL returns users to authentication API applications when using redirectless mode

NewPF-33983

When you use OAuth and OpenID Connect flows with response_mode=pi.flow, users are redirected back to the associated authentication application rather than to PingFederate. This is enables more consistent user journeys. For more information, see Configuring self-service account recovery.

Amazon DynamoDB account linking

NewPF-33988

To further support Amazon DynamoDB use cases, now you can also use account linking with this NoSQL database. For more information, see Configuring an Amazon DynamoDB for account-link storage.

Optional input and output contracts for policy fragments

NewPF-33332

This feature simplifies the use of PingFederate policies because it no longer requires input or output contracts for certain fragments. This improves the readability, maintainability, and performance of these policies. For more information, see Defining policy fragments.

OpenBanking plugin support for the dpop_bound_access_tokens parameter

NewPF-33631

Enhancing PingFederate's support for OAuth DPoP, this release includes support for this type of access token. It lets developers learn more about the use and importance of the dpop_bound_access_tokens parameter. For more information about the parameter, see the PingFederate Open Banking Software Assertion Validator plug-in on GitHub.

Toggle plugin creation/initialization during startup

NewPF-34640

In rare cases where plugin creation and initialization significantly slows down PingFederate startup, you can now turn off plugin creation and initialization. Plugins will then only be initialized on first use.

The default startup behavior is recommended for most customers. For more information about this option and the tradeoffs involved in enabling it, open a support case.

PingOne Protect Integration Kit

NewPF-34147

The PingOne Protect Integration Kit is now bundled with PingFederate.

PingID Integration Kit

ImprovedPF-34369

The PingID Integration Kit has been updated to version 2.26.

PingOne MFA Integration Kit

ImprovedPF-34368

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

Java 17 support for Thales Luna Network HSM integration

ImprovedPF-34168

When integrating with Thales Luna Network hardware security modules (HSMs), you can now use Java 17.

For more information, see Integrating with Thales Luna Network HSM

Improved OGNL expression logging

ImprovedPF-34050

The administrator audit log file (admin.log) now logs any OGNL expression tests performed and the expression variables used with an event type of TEST_EXPRESSION. For more information, see Administrator audit logging.

Improved CSD

ImprovedPF-33095
The Collect Support Data (CSD) script has been improved to capture more details.

Authenticating to Azure SQL Managed Instance through Azure Active Directory

ImprovedPF-33621

Now PingFederate supports authentication to Azure SQL Managed Instance through Azure Active Directory without a username and password. For more information, see Configuring a JDBC connection.

Upgraded BCFIPS library

ImprovedPF-32747

Upgraded the BCFIPS library to 1.0.2.4, which now supports enabling BCFIPS mode with Java 17.

For more information, see Bouncy Castle FIPS provider and Integrating Bouncy Castle FIPS providers.

Upgraded third-party libraries

Improved
  • Upgraded Jetty to version 9.4.53.v20231009.

  • Upgraded JGroups to version 4.2.24.Final.

Resolved issues

Improved client authentication security

SecurityPF-34645

Fixed a potential security vulnerability described in SECADV040.

Resolved a vulnerability in the Initial Setup Wizard

SecurityPF-34646

Fixed a Server-Side Request Forgery vulnerability in the Initial Setup Wizard described in security advisory SECADV041.

Prevent JGroups thread pool exhaustion in large clusters

FixedPF-34718

For fresh installs, we changed the default value of pf.cluster.TCPPING.return_entire_cache in jgroups.properties from true to false.

This prevents an issue where remote procedure calls (RPCs) can be dropped in large clusters that use TCPPING.

For more information, see Upgrade considerations.

Swagger response for oauth/accessTokenMappings

FixedPF-34500

Fixed an issue with the administrative API doc on the /oauth/accessTokenMappings endpoint not matching the actual endpoint response.

multi-value contains DN in policy rule check no longer case-sensitive

FixedPF-33560
Policy Rules conditions that use multi-value contains DN now ignore case while comparing the DN value.

Log messages about illegal characters in API calls

FixedPF-33305

Now log messages about illegal characters in API calls are logged at the DEBUG level rather than the WARN level.

Support for none as a valid token endpoint value

FixedPF-34115

Added the value none to /.well-known/openid-configuration/token_endpoint_auth_methods_supported

The id_token_jti property in token endpoint responses

FixedPF-34210

The id_token_jti property is no longer included in token endpoint responses.

Administrative API defect when fragment rules have Default to Success disabled

FixedPF-34216

Fixed an administrative API defect when a fragment rule had Default to Success disabled

Fixed /idp/startSLO.ping 404 caused by virtual issuer configuration

FixedPF-34322

Fixed an issue that was returning a 404 error if the /idp/startSLO.ping endpoint was hit while a virtual issuer was configured. You can now configure virtual issuers with a context path.

Client JWKS now sets properly when using DynamoDB storage

FixedPF-34504

Clients that maintain a JWKS endpoint can now use private key JWT based authentication when requesting an access token.

Fixed NPE when checking an existing persistent grant that is expired with DynamoDB

FixedPF-34606

Checking for existing but expired grants with DynamoDB no longer causes a null pointer exception error (NPE).

Connections close after getting a 401 or 403 from PingOne API

FixedPF-34545

Fixed an issue preventing PingFederate from closing connections after receiving a 401 or 403 response from PingOne MFA.

PingFederate systematically adds server-side sort control

FixedPF-33466

You can now turn off server-side sorting via a configuration option.

Unable to copy and paste policy contract in specific situations

FixedPF-34433

You can now copy and paste a policy contract below a selector node.

XML decryption failing with KeyName element

FixedPF-34536

Fixed an issue where decryption of an encrypted SAML element could fail if a KeyName was specified.

One-time link in password-reset email messages

FixedPF-33983

When using redirectless mode, now the one-time link (OTL) in password-reset email messages returns users to the authentication API application configured for the policy, rather than to PingFederate.

Incorrect error template when using service provider authentication policies

FixedPF-34111

When a service provider (SP) authentication policy fails, PingFederate now renders the sp.sso.error.page.template.html page instead of the idp.sso.error.page.template.html page.

Updating OAuth clients with dynamic client registration

FixedPF-34146

Fixed a defect where an OAuth client created with dynamic client registration (DCR) couldn't be updated with DCR after it was modified with the administrative console.

Idle JDBC datastore connections

FixedPF-34163

Now PingFederate closes idle JDBC datastore connections until the minimum pool size is reached instead of closing and recreating all of them.

The id_token_jti property in token endpoint responses

FixedPF-34210

The id_token_jti property is no longer included in token endpoint responses.

Administrative API defect when fragment rules have Default to Success disabled

FixedPF-34216

Fixed an administrative API defect when a fragment rule had Default to Success disabled

Email notifications for licensing events even when disabled

FixedPF-34225

Resolved an issue that caused PingFederate to send email notifications for licensing events even though they were disabled in the Runtime Notifications configuration.

Jetty library upgrade

FixedPF-31865

We upgraded the Jetty library, resolving CVE-2022-2047 and CVE-2022-2048.

OAuth scope names

FixedPF-33056

Using submit and onSubmit as OAuth scope names in the administrative UI drop-down no longer causes front-end JavaScript errors.

Policy fragment validation error

FixedPF-33156

Policy fragments with valid authentication sources no longer fail with an Invalid Configuration error during runtime.

Eliminating redundant group updates

FixedPF-33441

PingFederate, when configured with PingDirectory as an outbound provisioning data source, no longer sends redundant group updates in each provisioning cycle when the entry remains unchanged.

Potential security vulnerability

FixedPF-33449

We've resolved a potential security vulnerability that is described in security advisory SECADV037.

PingFederate as a Windows service

FixedPF-33450

We fixed an issue so that PingFederate as a Windows service now runs on Java 17. When updating to the latest maintenance release using an in-place update method (for example, from 11.3.0 to 11.3.x), in addition to the steps in Updating to the latest maintenance release, you must remove the existing PingFederate Windows service. After removal, re-install the PingFederate Windows Service to apply this fix.

Authentication policy fail path

FixedPF-33519

When an OIDC identity provider (IdP) connection fails in an authentication policy, PingFederate now continues on to the fail path of the authentication policy.

Fragment mapping validation error

FixedPF-33722

We resolved an issue that incorrectly produced an administrative API validation error when the fragment mapping references context.RequestedUser as the mapping source.

Authorization details within a RAR

FixedPF-33863

PingFederate now processes authorization details within a rich authorization request (RAR) as a JSON Array in a JWT request. Additionally, PingFederate no longer supports authorization details sent as stringified JSON arrays.

Cluster engine nodes starting without replication data

FixedPF-33881

Resolved a replication issue that, in rare cases, caused an engine node in a cluster to start without replication data from other nodes.

Server error when revoking user sessions

FixedPF-33920

Resolved an issue that prevented user sessions from being revoked through the session management API when using persistent sessions.

Potential security vulnerability

FixedPF-33935

We've resolved a potential security vulnerability that is described in security advisory SECADV037.

Fragment mapping validation errors

FixedPF-33957

When utilizing the PingFederate administrative API to create or update a fragment that includes another fragment, the API will no longer produce a validation error when fragment mapping involves an input source type.

Updated template variable

FixedPF-34016

The message-template-end-user-password-change.html template now contains the USERNAME variable.

Potential security vulnerability

FixedPF-34017

We've resolved a potential security vulnerability that is described in security advisory SECADV037.

Policy evaluation issue

FixedPF-34051

We fixed a policy evaluation issue that occurred when ui_locales was present in an authentication request.

Certificate import improvements

FixedPF-34074

We updated the administrative UI to include certification serial number in the drop-down, thus preventing import errors for certifications sharing the same Subject DN and expiration date combination.

DynamoDB attribute lookup error

FixedPF-34099

We fixed an attribute lookup error that occurred when different DynamoDB attributes shared an overlapping path.

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

PingOne MFA
Issue
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
  • 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 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.

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

SAML IdP Discovery and SAML SP Affiliations

Info

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

Text Message SSPR

Info

Starting with PingFederate 12.0, self-service password reset (SSPR) has been removed.

Upgrade from PingFederate 6.x and 7.x

Info

Starting with version 12.0, PingFederate no longer supports upgrading from PingFederate version 6.x and 7.x.

PingOne Fraud integration kit

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

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.