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.
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:
- Get a list of provisioning channel IDs:
provmgr --show-channels
- 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:
- Edit the org.sourceid.common.SqlFilterManager.xml file.
- 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>
- Save the file.
- Restart PingFederate.
If you have a clustered PingFederate environment:
- Perform the steps above on the console node.
- Sign on to the PingFederate administrative console.
- Go to the screen.
- Click Replicate Configuration to push this change to all engine nodes.
- 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:
- Edit <pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.jdbc.DataSourceDeployerFactory.xml.
- Replace
dbcp
withbonecp
. - Save the file.
- Restart PingFederate.
If you have a clustered PingFederate environment:
- Perform the steps above on the console node.
- Sign on to the PingFederate administrative console.
- Go to the screen.
- Click Replicate Configuration to push this change to all engine nodes.
Support for BoneCP as the JDBC connection pool library has been deprecated and will be removed in a future release.
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.
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.