Specific tables are required in order for PingFederate to store OAuth client records on your database server. Table-setup scripts are provided for supported database servers.

CAUTION:

PingFederate does not migrate client records from one storage medium to another. You must recreate your clients after updating the client storage configuration. If you need only a few clients, you can recreate them using the administrative console.

If you need a large number of clients, you may use the administrative API to retrieve your client records (before updating the client storage), update the client storage configuration, and recreate your clients using the administrative API based on the retrieved records. For more information, see PingFederate administrative API.

CAUTION:

A pre-installed, default HSQLDB database is selected for initial setup and testing. However, we strongly recommend that you 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 may cause various problems due to its limitations and HSQLDB involved cases are not supported by PingIdentity.

  1. Edit the <pf_install>/pingfederate/server/default/conf/META-INF/hivemodule.xml file.
    1. Locate the ClientManager service point: 
      <!-- Service for storing OAuth client configuration. -->
<service-point id="ClientManager" interface="org.sourceid.oauth20.domain.ClientManager">
    <invoke-factory>
        <!--
        Supported classes are
        org.sourceid.oauth20.domain.ClientManagerXmlFileImpl ...
        org.sourceid.oauth20.domain.ClientManagerJdbcImpl    ...
        org.sourceid.oauth20.domain.ClientManagerLdapImpl    ...
        org.sourceid.oauth20.domain.ClientManagerGenericImpl ...
        -->
        <construct class="org.sourceid.oauth20.domain.ClientManagerXmlFileImpl"/>
    </invoke-factory>
</service-point>
    2. Update the class attribute value to org.sourceid.oauth20.domain.ClientManagerJdbcImpl.
    3. Save the file.
    Important:

    For a clustered PingFederate environment, edit the hivemodule.xml file on each node.

    Additionally, you must set up an external database because the bundled HSQLDB database cannot be shared across multiple PingFederate engine nodes. For production standalone deployments, it is also recommended to store the client records in an external secured database.

    Follow the remaining steps to set up an external database for client storage.

  2. Run the table-setup scripts for your database server provided in the <pf_install>/pingfederate/server/default/conf/oauth-client-management/sql-scripts directory.
  3. If you have not already done so, create a JDBC datastore for your database server on the System > Data Stores screen.
  4. Copy the system ID of the applicable JDBC datastore from the System > Data Stores screen.
  5. Edit the org.sourceid.oauth20.domain.ClientManagerJdbcImpl.xml file, located in the <pf_install>/pingfederate/server/default/data/config-store/ directory.
    Note:

    For a clustered environment, edit this file on the administrative console node first, and then replicate to other engine nodes using System > Server > Cluster Management as explained in later steps.

    Replace the <c:item name="PingFederateDSJNDIName"/> element value with the system ID of your datastore connection and save the file.

    For example, if the system ID is JDBC-123456789ABCDEF123456789ABCDEF123456A0AC, update the org.sourceid.oauth20.domain.ClientManagerJdbcImpl.xml file as follows:

    <?xml version="1.0" encoding="UTF-8"?>
<c:config xmlns:c="http://www.sourceid.org/2004/05/config">
    <c:item name="PingFederateDSJNDIName">JDBC-123456789ABCDEF123456789ABCDEF123456A0AC</c:item>
</c:config>
  6. Start or restart the PingFederate service.
    Note:

    For a clustered PingFederate environment, replicate this new configuration to other engine nodes on the System > Cluster Management screen; then start or restart the PingFederate service on each engine node to activate the change.