Occasionally, PingFederate introduces database-related changes, such as adding a new table, modifying an existing table, or updating connection pool library, for the purpose of product improvement.

Additionally, neither the Upgrade Utility nor the PingFederate installer for Windows migrates data maintained in the internal HSQLDB database or any external database. For instance, if outbound provisioning is enabled in the new PingFederate instance using the internal database, it is re-initialized from the provisioning source.

CAUTION:

Use the built-in HSQLDB only for trial or training environments. For testing and production environments, always use a secured external storage solution for proper functioning in a clustered environment.

Testing involving HSQLDB is not a valid test. In both testing and production, it might cause various problems due to its limitations and HSQLDB involved cases are not supported by PingIdentity.

If your PingFederate environment connects to one or more database servers, review the following information and make changes accordingly.

Provisioning datastore reset

Upgrading to PingFederate 9.0 or 9.0.1 when using its outbound provisioning capability can result in user records being disabled at SaaS applications. The issue has since been resolved in version 9.0.2.

If you are upgrading from version 8.4.4 (or an earlier version) or 9.0.2 to version 10.0, the upgrade process automatically resolves this issue. No further action is required.

If you are upgrading from version 9.0 or 9.0.1 to version 10.0, use the following provmgr commands to reset the provisioning datastore on the upgraded installation:

  1. Get a list of provisioning channel IDs:

    provmgr --show-channels

  2. Reset the provisioning datastore for a given channel by its ID:

    provmgr -c channel_id --reset-all

    Note:

    If you have multiple provisioning channels, run the command for each channel. (The order of the parameters does not matter.)

The provmgr command-line tool is located in the <pf_install>/pingfederate/bin directory: provmgr.bat for Windows and provmgr.sh for Linux. For more information about the provmgr command-line tool, see Outbound provisioning CLI.

Security enhancement in JDBC datastore queries

A security enhancement has been made in PingFederate 9.0 to safeguard JDBC datastore queries against back-end SQL injection attacks. This protection is enabled for all new installations.For upgrades, you can enable this protection by modifying the org.sourceid.common.SqlFilterManager.xml file, located in the <pf_install>/pingfederate/server/default/data/config-store directory.

To enable this security enhancement:

  1. Edit the org.sourceid.common.SqlFilterManager.xml file.
  2. Set the <item name="enableSqlFilters"/> element value to true; for example:
    <?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://www.sourceid.org/2004/05/config">
    <item name="enableSqlFilters">true</item>
</config>
  3. Save the file.
  4. Restart PingFederate.

    If you have a clustered PingFederate environment:

    1. Perform the steps above on the console node.
    2. Sign on to the PingFederate administrative console.
    3. Go to the System > Cluster Management screen.
    4. Click Replicate Configuration to push this change to all engine nodes.
  5. Verify your use cases to make sure your search filters return the expected results.

An improved index in the database table for OAuth clients

Applicable only to customers who had configured PingFederate to store OAuth clients on a database server.

PingFederate 8.4 added the value column to an existing index (IDX_FIELD_NAME) in the pingfederate_oauth_clients_ext table as a general improvement.

You must modify the index in your existing pingfederate_oauth_clients_ext table.

While there is no alter-table script provided, you can derive the setup from the new table-setup scripts, oauth-client-management-<databaseServer>.sql, found in the <pf_install>/pingfederate/server/default/conf/oauth-client-management/sql-scripts directory. Consult with your database administrator, as needed.

New connection pool library

As of PingFederate 8.0, support for BoneCP as the JDBC connection pool library has been deprecated and replaced with Apache Commons DBCP 2, which requires JDBC 4.1 (or more recent) drivers.

Verify the database-driver JAR files, found in the <pf_install>/pingfederate/server/default/lib directory, meet the minimum version requirement. If you are using JDBC drivers of version 4.0 (or earlier), contact your vendors for the latest drivers and replace the older JDBC database-driver JAR files with the latest.

Alternatively, if you prefer to upgrade the older JDBC drivers at a later time, use the following steps to revert the JDBC connection pool library to BoneCP:

  1. Edit <pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.jdbc.DataSourceDeployerFactory.xml.
  2. Replace dbcp with bonecp.
  3. Save the file.
  4. Restart PingFederate.

    If you have a clustered PingFederate environment:

    1. Perform the steps above on the console node.
    2. Sign on to the PingFederate administrative console.
    3. Go to the System > Cluster Management screen.
    4. Click Replicate Configuration to push this change to all engine nodes.
Important:

Support for BoneCP as the JDBC connection pool library has been deprecated and will be removed in a future release.

Note:

PingFederate has been tested with vendor-specific JDBC 4.2 drivers. For more information, see Database driver information. To obtain your database driver JAR file, contact your database vendor. Database driver file should be installed to the <pf_install>/pingfederate/server/default/lib directory. You must restart the server after installing the driver.

Changes in the database tables for log messages

Applicable only to customers who have configured Log4j or Log4j 2 to write log messages to database tables on Microsoft SQL Server.

For performance reasons, PingFederate 8.0 started using the NVARCHAR data type instead of the VARCHAR data type. The table-setup scripts (targeted for Microsoft SQL Server) in the <pf_install>/pingfederate/server/default/conf/log4j/sql-scripts directory have been updated. If you are upgrading from PingFederate 7.3 or an earlier version, consider updating the data type in the applicable tables accordingly for performance reasons.

Changes in the database table for account linking

Applicable only to customers who have created a database table for account linking on Microsoft SQL Server.

For columns in the pingfederate_account_link table using the VARCHAR data type, PingFederate 7.3 updated the data type to NVARCHAR for performance reasons. The table-setup script, account-linking-sqlserver.sql, in the <pf_install>/pingfederate/server/default/conf/account-linking/sql-scripts directory has been updated. If you are upgrading from PingFederate 7.2 R2 or an earlier version, consider updating the data type in the pingfederate_account_link table accordingly for performance reasons. Consult with your database administrator, as needed.

Changes in the database tables for OAuth clients

Applicable only to customers who have deployed Microsoft SQL Server to store their OAuth clients.

For columns in the pingfederate_oauth_clients and pingfederate_oauth_clients_ext tables using the VARCHAR data type, PingFederate 7.3 updated the data type to NVARCHAR for performance reasons. The table-setup script, oauth-client-management-sqlserver, in the <pf_install>/pingfederate/server/default/conf/oauth-client-management/sql-scripts directory has been updated. If you are upgrading from PingFederate 7.2 R2 or an earlier version with OAuth use cases, consider updating the data type in both tables accordingly for performance reasons. Consult with your database administrator, as needed.

Changes in the database tables for OAuth persistent grants and extended attributes

Applicable only to customers who have deployed Microsoft SQL Server to host their OAuth grant datastore.

For columns in the pingfederate_access_grant and pingfederate_access_grant_attr tables using the VARCHAR data type, PingFederate 7.3 updated the data type to NVARCHAR for performance reasons. The table-setup scripts (targeted for Microsoft SQL Server) in the <pf_install>/pingfederate/server/default/conf/access-grant/sql-scripts directory have been updated. If you are upgrading from PingFederate 7.2 R2 or an earlier version with OAuth use cases, consider updating the data type in both tables accordingly to avoid potential issues caused by incompatible data types between these two tables. Consult with your database administrator, as needed.

A new database table for OAuth persistent grant extended attributes

PingFederate 7.2 R2 introduced the capability to map attributes from initial authentication context to an access token attribute contract, which requires an update in the OAuth grant datastore. If you are upgrading from PingFederate 7.2.1 or an earlier version with OAuth use cases, run the table-setup script, access-grant-attribute-<database>.sql, found in the <pf_install>/pingfederate/server/default/conf/access-grant/sql-scripts directory for your database server. Consult with your database administrator, as needed.

New indexes in the database table for OAuth persistent grants

Since PingFederate 7.1 R3, a couple of indexes have been added to the pingfederate_access_grant table.

PingFederate version Column Index
7.3 expires EXPIRESIDX
7.1 R3 client_id CLIENTIDIDX

If you are upgrading from PingFederate 6.5 through 7.1.4, you must add both indexes to your existing pingfederate_access_grant table.

If you are upgrading from PingFederate 7.1 R3, 7.2.x, or 7.2 R2, you must add the EXPIRESIDX index for the expires column.

While there is no alter-table script provided, you can derive the setup from the new table-setup scripts, access-grant-<databaseServer>.sql, found in the <pf_install>/pingfederate/server/default/conf/access-grant/sql-scripts directory. Consult with your database administrator, as needed.

Changes in a database table supporting nested group membership

Outbound provisioning of groups and nested group membership requires an update in the internal datastore.

If you are upgrading from PingFederate 8.0.x, no action is required.

If you are upgrading from PingFederate 7.1.x through 7.3, consider running the alter-table script, add-subgroup-membership-<database>.sql, found in the <pf_install>/pingfederate/server/default/conf/provisioner/sql-scripts/updates directory for your database server to update the existing group_membership table. Consult with your database administrator, as needed.

If you are upgrading from PingFederate 7.0.1 or an earlier version, consider using the table-setup script, provisioner-<database>.sql, found in the <pf_install>/pingfederate/server/default/conf/provisioner/sql-scripts directory for your database server as a reference to add the new group_membership table to your existing internal datastore.

Alternatively, you may create a new database using the table-setup script and let the outbound provisioner repopulate the new internal datastore on its next run, regardless of the current version of your PingFederate.

CAUTION:

The table-setup script removes the existing (outbound provisioning) tables. If you wish to keep a copy of the current data, use the tools available from your database vendor to make a backup before running the table-setup script.

Consult with your database administrator, as needed.