PingFederate Server

PingFederate 12.2 (December 2024)

New features and improvements in PingFederate 12.2.

New features and enhancements

Extended properties in adapter contract mapping

New PF-36314

We’ve added the ability for PingFederate to read extended properties in adapter contract mappings.

This improves flexibility by allowing you to use extended properties as values for attributes fulfilled by your adapter or as lookup values from your datastore.

Learn more in Configuring IdP adapter contract fulfillment and Defining issuance criteria for IdP adapter contract.

Extended properties in token generator and token exchange policy processor mappings

New PF-36315

We’ve added the ability for PingFederate to read extended properties in token generator mappings and token exchange policy processor mappings.

This improves flexibility by allowing you to use extended properties in token generation and exchange operations. You can also use extended properties as lookup values from your data store.

Extended properties in IdP and SP connections

New PF-36316

We’ve added the ability for PingFederate to read extended properties in adapter and authentication policy contract (APC) mappings for browser single sign-on (SSO).

This improves flexibility by allowing you to use extended properties in identity provider (IdP) and service provider (SP) connections.

Learn more in Configuring target session fulfillment.

Kerberos token validation without direct KDC communication

New PF-35864

We’ve added support for Kerberos validation when PingFederate is deployed in the cloud without direct Key Distribution Center (KDC) connectivity.

This can improve performance by allowing PingFederate to validate Kerberos tickets locally without the need for additional components.

Learn more in Adding Active Directory domains and Kerberos realms.

Authentication policy logging improvements

New PF-35343

We’ve improved the logging of authentication policies and fragments used during authentication. The following items are now included in their respective log files:

  • server.log

    • Authentication policies that are skipped (DEBUG level)

    • Authentication policies used in the authentication request (DEBUG level)

    • No match found for rules (DEBUG level)

  • audit.log

    • Policies used in authentication request (INFO level)

Learn more about the audit.log changes in Security audit logging.

URL-encoded certificate headers

New PF-36649

We’ve added a feature that allows PingFederate to consume URL-encoded client certificate headers.

This improves compatibility with NGINX mTLS-terminating reverse proxy.

Learn more in Configuring incoming proxy settings.

Automatic configuration data upgrade

New PF-34426

We’ve added a feature that automatically upgrades an imported configuration data archive from an older version of PingFederate to be compatible with the current version.

This makes it easier to upgrade to newer versions of PingFederate by allowing you to upgrade your configuration data without using the Upgrade Utility.

Learn more in Upgrading configuration data and Importing and deploying administrative console configuration data.

Automatic configuration data replication

New PF-36296

We’ve added a feature that allows PingFederate to automatically replicate configuration data archives to clustered server nodes when they uploaded to the drop-in deployer.

This makes it easier to ensure that your clustered nodes have the same configuration data.

Learn more in Upgrading configuration data and Configuration-archive deployment.

Token exchange processor policies in persistent grants

New PF-35857

We’ve added a feature that allows you to also get a refresh token during OAuth token exchange.

This allows you to make extended interactions without using long-lived access tokens received from token exchange.

Learn more in Managing processor policy grant mapping.

Token Endpoint response customization

New PF-35863

We’ve added a feature that allows you to customize which attributes are returned in the Token Endpoint response based on the scopes that are included in the request.

This improves flexibility by giving you more control over where PingFederate can return attributes.

Learn more in Defining the token endpoint management contract.

Admin API error response

New PF-36602

We’ve improved the error output for the Administrative API. When access to the administrative API in configured to use OAuth 2.0 or JWT authorization, and the access token is invalid, the error response now includes both error and error_description in the WWW-Authentication header.

This improves troubleshooting by providing an error code and description when authorization fails.

CIDR Authentication Selector description field

New PF-36291

We’ve added an optional description field to the CIDR Authentication Selector.

This helps you keep track of your defined network ranges by giving them an easily identifiable name.

Learn more in Configuring the CIDR Authentication Selector.

ID token included in token exchange

New PF-35859

We’ve added a feature that allows PingFederate to include an ID token along with an access token and refresh token in OAuth token exchanges.

This can improve your end-user experience by passing ID token information along with access tokens during SSO and other token exchange operations.

Learn more in Configuring policy and ID token settings.

Logs in JSON format

New PF-36317

We’ve added support for JSON formatted logging for most PingFederate logs through the log4j2 logging library.

This improves your ability to monitor PingFederate perfomance by producing logs in an easily parsed standard format.

Learn more in Logging in JSON format.

Collect support data in the admin console

New PF-35420

We’ve added a feature that allows you to collect support data using the administrative console and the administrative API.

This will improve your Ping Identity Support experience by allowing you to more easily customize and collect support data.

Learn more in Collecting support data in the administrative console.

OAuth client name in HTML form templates

New PF-29353

We’ve added the ability to include the name of OAuth clients in HTML form login templates. You can use the $escape utility with the $clientName variable to include the client name.

This allows you to track the name of the client you use when customizing user-facing login pages.

Learn more in Customizable user-facing pages.

TLS 1.3 support for HSMs

New PF-35854

We’ve added TLS 1.3 support for Hardware Security Modules (HSMs). New installations of PingFederate will have TLS 1.3 enabled by default when in HSM mode.

This improves security by adding TLS by default to your HSM, and streamlines the HSM configuration process by removing a step to manually add TLS.

Device authorization grants include server settings

New PF-35858

We’ve added a feature that allows PingFederate to return ID tokens when issuing OpenID device authorization grants.

This allows you to personalize response messages during device authorization flows. For example, you can display the user’s name as part of the authorization message.

Learn more in Configuring authorization server settings.

Google Cloud KMS Support

New PF-36302

We’ve added support for Google Cloud Key Management System (KMS).

This improves security by allowing you to encrypt the master key file when PingFederate is running in Google Cloud Platform.

Learn more in Implementing a MasterKeyEncryptor using Google Cloud KMS.

Disable MaxMaliciousActions parameter globally

New PF-36298

We’ve made it possible to globally disable the MaxMaliciousActions parameter in the <pf-install>/pingfederate/server/default/data/config-store/com.pingidentity.common.security.AccountLockingService.xml file.

This prevents an issue during upgrades where PingFederate unintentionally locks out an OAuth client when it tries to revoke invalid Reference Bearer Access Tokens.

Override MaxMaliciousActions parameter for OAuth client

New PF-36299

We’ve made it possible to override the MaxMaliciousActions parameter in the <pf-install>/pingfederate/server/default/data/config-store/com.pingidentity.common.security.AccountLockingService.xml file as it applies to an OAuth client.

This prevents an issue during upgrades where PingFederate unintentionally locks out an OAuth client when it tries to revoke Reference Bearer Access Tokens.

We’ve also improved the error messaging to clarify when it’s the client, not the account, that’s locked out.

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

Admin API JWT authorization

New PF-35855

We’ve added new feature that allows clients to access the Administrative API using a JSON Web Token (JWT).

This improves flexibility by adding a new secure method for your applications to access PingFederate administrative functions.

Learn more in Enabling JWT authorization.

OAuth Admin API access token scopes are optional

New PF-36588

PingFederate can now accept OAuth access tokens without scopes through the Admin API.

JGroups maximum thread pool size

New PF-34715

We’ve moved the setting for JGroups maximum thread pool size from tcp.xml and udp.xml to run.properties.

This new parameter in the run.properties file allows you to configure your JGroups thread pool more easily and ensure that changes are carried over during upgrade.

Learn more in Deploying cluster servers.

Customize Jetty runtime logs format

New PF-32832

We’ve added the jetty.runtime.requestlog.format property to the run.properties file to allow you to customize the format of the Jetty runtime log request.

You can use this property to add milliseconds to your log format, which is helpful for troubleshooting high volumes of requests.

Learn more in Configuring PingFederate properties.

Google reCAPTCHA Enterprise support

New PF-35861

We’ve added support for Google reCAPTCHA Enterprise.

reCAPTCHA Enterprise can handle higher volumes of assessment transactions and offers more levels of bot score granularity.

Learn more in Configuring Google reCAPTCHA Enterprise.

UserInfo endpoint JWT support

New PF-35862

We’ve added JSON web token (JWT) support to PingFederate’s UserInfo endpoint when acting as the OpenId provider (OP). As the relying party (RP), PingFederate now supports consuming JWT-based responses from other OPs UserInfo endpoint.

This improves security by replacing information sent in JSON form with a signed token, an encrypted token, or both.

Learn more in Configuring OAuth clients and OAuth Client Management Service.

Improved provisioner logging

Improved PF-28890

We’ve added a new provisioner-channel-summary.log file to capture data about users and groups added, removed, and updated by provisioning cycles. We’ve also added new information at the INFO level to the provisioner.log and provisioner-audit.log files.

These updates give you improved summary information about provisioning operations without the unnecessary detail of DEBUG-level logging.

Learn more in PingFederate log files.

PingOne Verify Integration Kit update

Improved PF-36573

The PingOne Verify Integration Kit has been updated to version 2.2.2.

PingOne MFA Integration Kit update

Improved PF-36573

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

Microsoft EAM

PingFederate now supports Microsoft External Authentication Method (EAM) to handle multi-factor authentication (MFA) flows with PingID or other MFA integrations.

Learn more in Microsoft EAM Integration Kit.

Active Directory 2022 compatibility

Info PF-35782

We’ve confirmed that PingFederate 12.2 and 12.1 are compatible with Microsoft Active Directory 2022.

PostgreSQL 16.4 and 17 compatibility

Info PF-36312 PF-36288

We’ve confirmed that PingFederate version 12.2 is compatible with PostgreSQL versions 16.4 and 17.

Amazon Aurora PostgreSQL 16.4 compatibility

Info PF-36289

We’ve confirmed that PingFederate is compatible with Amazon Aurora PostgreSQL version 16.4.

jose4j library

Info PF-36445

PingFederate now uses the jose4j library version 0.9.6.

Apache Commons Compress

Info PF-36446

PingFederate now uses Apache Commons Compress library version 1.27.1.

AWS KMS library

Info PF-36579

We’ve upgraded the Amazon Web Services (AWS) Key Management Service (KMS) master-key-encryptor library to the latest version as of this release.

Correlation ID request header

Info PF-36675

Forward slashes are now valid characters in the request header for correlation ID.

Learn more in General settings and Correlating PingFederate events with PingDirectory LDAP activities.

Provisioning Flag Comparison Value now case-insensitive

info PF-36276

We’ve updated the provisioning Flag Comparison Value attribute to be case-insensitive.

Learn more in Modifying source settings.

Resolved issues

Auditor access to LDAP credentials

Security PF-35092

We’ve fixed a security vulnerability that could have allowed auditors to access LDAP credentials stored in configured datastores.

IP addresses accessible using Partner Metadata URL loader

Security PF-35279

We’ve fixed a security vulnerability that could have allowed malicious actors to use the Partner Metadata URL loader to list the IP addresses of network assets.

ValidateRelayStateLength parameter

Fixed PF-35847

We’ve fixed a defect that cause the ValidateRelayStateLength parameter in the org.sourceid.saml20.bindings.AbstractAsyncBinding.xml file to be evaluated only on startup. Now, the parameter is always evaluated in runtime flows.

Unexpected error when replicating an active admin console

Fixed PF-35919

We’ve fixed a defect that caused PingFederate to return an unexpected error when replicating on a newly promoted passive admin node after deleting connections or clients on the previously active admin node.

Kerberos and Form SSO policy fails in iOS

Fixed PF-35990

We’ve fixed a defect that caused Kerberos and Form SSO policies to fail when a user attempted SSO using iOS.

Provisioning character limit

Fixed PF-36035

We’ve fixed a defect that caused outbound provisioning to fail and cease if a source user object exceeded a 255-character limit. In the new behavior, PingFederate will skip user objects that exceed 255 characters and log a warning.

Redirect Host header validation

Fixed PF-36040

PingFederate now validates the Host header when determining where to send redirect requests. The Host header is validated against the PingFederate host name, as well as any configured virtual hosts.

PingDirectory password warning

Fixed PF-36232

We’ve fixed a defect that prevented PingFederate from issuing a password expiration warning when using PingDirectory as a datastore.

Multiple application requests within a browser

Fixed PF-36239

We’ve fixed a defect that could cause inconsistent sessions or authentication errors when starting multiple applications in different browser tabs at the same time.

Unsupported data archive using drop-in deployer

Fixed PF-36478

We’ve fixed a defect that caused PingFederate to fail to restart when forcing an import of an unsupported configuration data archive using the drop-in deployer.

Replication warning banner

Fixed PF-36546

We’ve fixed a defect that caused the banner message warning that a configuration is out of date to persist after a configuration had been replicated. This defect occurred when running PingFederate as a Windows service.

Missing log details

Fixed PF-36550

We’ve fixed a defect that caused PingFederate to log errors excluding details of what error occurred. The fix now includes missing details.

Email verification failure after registration workflow

Fixed PF-36574

We’ve fixed a defect that caused the email verification screen to fail to appear when a user registered through an authentication source.

Multi-part refresh token revocation failure

Fixed PF-36600

We’ve fixed an issue that caused PingFederate to fail to revoke multi-part refresh tokens through the revoke_token.oauth2 endpoint.

Known issues and limitations

PingOne Verify IK unexpected error

Issue PF-36573

PingFederate returns an unexpected error when you create an instance of the PingOne Verify Integration Kit version 2.2.2 in PingFederate with the Verify feature in PingOne disabled.

Reencrypt data archive failure with Google Cloud KMS

Issue PF-36487

When PingFederate is configured to use the Amazon Web Services or Google Cloud Platform Key Management System (KMS), importing a valid configuration data archive with Reencrypt Data enabled fails with a Could not reencrypt data archive error message. This failure causes PingFederate to fail to restart.

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.

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

  • 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 with Oracle JDK 11 and 17.

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 with Oracle JDK 11 and 17.

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 with Oracle JDK 11 and 17.

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

No features were deprecated for PingFederate 12.2.