--- title: Configuring external databases for client storage description: 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. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configuring_external_databases_client_storage canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_external_databases_client_storage.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: March 15, 2023 section_ids: about-this-task: About this task steps: Steps example: Example: related-links: Related links configuring-an-amazon-dynamodb-for-client-storage: Configuring an Amazon DynamoDB for client storage before-you-begin: Before you begin about-this-task-2: About this task steps-2: Steps --- # Configuring external databases for client storage ## About this task 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. Learn more about supported datastores for OAuth client storage in [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingFederate doesn't 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, 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. Learn more in [PingFederate administrative API](../developers_reference_guide/pf_admin_api.html). | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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.Tests that involve HSQLDB aren't valid. In both testing and production, it might cause various problems due to its limitations and HSQLDB involved cases aren't supported by Ping Identity. | ## Steps 1. Edit the `/pingfederate/server/default/conf/service-points.conf` file. 1. Locate the `client.manager` service point. ``` # Service for storing OAuth client configuration. # Supported classes are # org.sourceid.oauth20.domain.ClientManagerXmlFileImpl : Use this service-point for an XML implementation. # org.sourceid.oauth20.domain.ClientManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.oauth20.domain.ClientManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.oauth20.domain.ClientManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation # org.sourceid.oauth20.domain.ClientManagerGenericImpl : Use this service-point if you have specified a custom ClientStorageManager implementation above. client.manager=org.sourceid.oauth20.domain.ClientManagerXmlFileImpl ``` 1. Update the value of the service point to `org.sourceid.oauth20.domain.ClientManagerJdbcImpl`. 2. Save the file. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You must set up an external database because you cannot share the bundled HSQLDB database across multiple PingFederate engine nodes. For production standalone deployments, we recommend you store the client records in an external secured database. | 2. Run the table-setup scripts for your database server provided in the `/pingfederate/server/default/conf/oauth-client-management/sql-scripts` directory. 3. If you haven't already done so, create a Java Database Connectivity (JDBC) datastore for your database server. Go to **System > Data & Credential Stores**. 4. In the **Data Stores** window, copy the system ID of the applicable JDBC datastore. 5. Edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.ClientManagerJdbcImpl.xml` file. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For a clustered PingFederate 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 `` element value with the system ID of your datastore connection and save the file. ### Example: If the system ID is `JDBC-123456789ABCDEF123456789ABCDEF123456A0AC`, update the `org.sourceid.oauth20.domain.ClientManagerJdbcImpl.xml` file as follows. ```xml JDBC-123456789ABCDEF123456789ABCDEF123456A0AC ``` 6. Start or restart PingFederate. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For a clustered PingFederate environment, replicate this new configuration to other engine nodes on **System > Server > Cluster Management**.Start or restart the PingFederate service on each engine node to activate the change. | ## Related links * [Configuring a JDBC connection](pf_configuring_jdbc_connection.html) * [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html) ## Configuring an Amazon DynamoDB for client storage Set up an Amazon DynamoDB so that PingFederate can store OAuth client records in the DynamoDB NoSQL database. ## Before you begin Ensure that your server is configured to access DynamoDB. ## About this task PingFederate requires specific tables to store OAuth client records on your DynamoDB server. Table-setup scripts are provided for this purpose. ## Steps 1. To create a table in DynamoDB to contain OAuth clients, run the commands in the `/pingfederate/server/default/conf/oauth-client-management/nosql-scripts/oauth-client-management-dynamodb.txt` file. 1. (Optional) To rename the table and index names, edit the `table-name` and `\"IndexName\"` values in the table script in the `oauth-client-management-dynamodb.txt` file. 2. Edit the `/pingfederate/server/default/conf/service-points.conf` file: 1. Locate the `ClientManager` service point: ``` # Service for storing OAuth client configuration. # Supported classes are # org.sourceid.oauth20.domain.ClientManagerXmlFileImpl : Use this service-point for an XML implementation. # org.sourceid.oauth20.domain.ClientManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.oauth20.domain.ClientManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.oauth20.domain.ClientManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation # org.sourceid.oauth20.domain.ClientManagerGenericImpl : Use this service-point if you have specified a custom ClientStorageManager implementation above. client.manager=org.sourceid.oauth20.domain.ClientManagerXmlFileImpl ``` 2. Update the value of the `class` attribute to `org.sourceid.oauth20.domain.ClientManagerDynamoDBImpl`. 3. Save the file. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | For a clustered PingFederate environment, you must edit the `service-points.conf` file on each node manually because cluster replication can't replicate this change to other nodes. | 3. (Optional) If you modified the default table and index names in the `oauth-client-management-dynamodb.txt` file in step 1, edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.ClientManagerDynamoDBImpl.xml` file to match your customized configuration. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you ran the script commands from the `oauth-client-management-dynamodb.txt` as is and did not change the default names in the commands, you do not need to edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.ClientManagerDynamoDBImpl.xml` file. | 1. Replace the ``, ``, ``, ``, and `` element values with the customized names created during your initial DynamoDB setup. 2. Save the file. The following table describes the preconfigured PingFederate variables in the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.ClientManagerDynamoDBImpl.xml` file. **DynamoDB Client Manager Variables** | Variable | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PingFederateSortedOAuthClientId-index` | The name of the OAuth client ID index. This index is used to support sorting by Client ID on the **Client Management Admin UI** page.This is the default value. | | `PingFederateSortedOAuthClientName-index` | The name of the OAuth client name index. This index is used to support sorting by Client Name on the **Client Management Admin UI** page.This is the default value. | | `PingFederateSortedOAuthClientLastModified-index` | The name of the OAuth client last modified index. This index is used to support sorting by Last Modified Time on the **Client Management Admin UI** page.This is the default value. | | `PingFederateSortedOAuthCreationTime-index` | The name of the OAuth client creation time index. This index is used to support sorting by Creation Time on the **Client Management Admin UI** page.This is the default value. | | `EndpointOverride` | An optional endpoint URL which should not be used in production but allows for testing with a local development DynamoDB instance.By default, this value is empty. To test DynamoDB running locally, specify `EndpointOverride` to point to a local endpoint. For example, `http://localhost:8000`. For more information, see [DynamoDB local usage notes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html) in the Amazon DynamoDB documentation. | | `dynamoDbBatchSize` | Number of records to request when performing batch operations against DynamoDB. The minimum allowed value is one, the maximum allowed value is 100, and the default value is 50. | | `ApiCallTimeout` | The amount of time in milliseconds to allow the client to complete the execution of the API call.The default value is 10000. | | `ApiCallAttemptTimeout` | The amount of time in milliseconds to wait for the HTTP request to complete before giving up and timing out.The default value is `1000`. | | `query-client-count` | The number of OAuth clients returned on search operations for 'Check Usage' pop-ups of resources referenced by clients. Negative values signify the retrieval of all clients.The default value is 2000. | 4. Start or restart the PingFederate service. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For a clustered PingFederate, replicate this new configuration to other engine nodes on **System > Server > Cluster Management**. Start or restart the PingFederate service on each engine node to active the change. | | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Frequent use of certain Admin UI operations, such as searching the **OAuth Client** list or detecting usage on various pages (**Access Token Management**, **OpenID Connect Policy Management**, **Token Exchange Processor Policies**, **CIBA Request Policies**, and **Trusted CAs**), may result in full table scans. This can impact the table's required Read Capacity. |