--- title: Configuring external databases for grant storage description: Specific tables are required in order for PingFederate to store grants, the associated attributes, and their values (if any), on your database server. component: pingfederate version: 12.3 page_id: pingfederate:administrators_reference_guide:pf_configuring_external_database_grant_storage canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_external_database_grant_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: September 18, 2026 superseded_by: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_external_database_grant_storage.html section_ids: about-this-task: About this task steps: Steps example: Example: result: Result configuring-an-aws-dynamodb-for-persistent-grant-storage: Configuring an AWS DynamoDB for persistent grant storage before-you-begin: Before you begin about-this-task-2: About this task steps-2: Steps result-2: Result related-links: Related links --- # Configuring external databases for grant storage Specific tables are required in order for PingFederate to store grants, the associated attributes, and their values (if any), on your database server. Table-setup scripts are provided for supported database servers. ## About this task Edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl.xml` file and the `/pingfederate/server/default/conf/service-points.conf` file. ## Steps 1. Run the table-setup scripts for your database server provided in the `/pingfederate/server/default/conf/access-grant/sql-scripts` directory. 2. If you haven't already done so, create a Java database connectivity (JDBC) *(tooltip: \
\

A Java API that allows Java programs to interact with databases.\

\
)* data store for your database server on **System > Data & Credential Stores > Data Stores**. 3. Copy the **System ID** of the applicable JDBC data store from the **Data Stores** window. 4. Edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl.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. | 1. Replace the `` element value with the system ID of your data store connection and save the file. ### Example: If the system ID is `JDBC-123456789ABCDEF123456789ABCDEF123456A0A6`, update the `org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl.xml` file as follows. ```xml JDBC-123456789ABCDEF123456789ABCDEF123456A0A6 ``` 5. Edit the `/pingfederate/server/default/conf/service-points.conf` file. 1. Go to the `# Service for storage of access grants` section. 2. Change the `access.grant.manager` service endpoint to the following: ``` ... access.grant.manager=org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl ... ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In clustered PingFederate environments, you must manually edit the `service-points.conf` file on each node because cluster replication can't replicate this change to other nodes. | 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. | ## Result PingFederate provides two cleanup tasks for persistent grants. One task manages expired grants, while another task caps the number of grants based on a combination of user, client, grant type, and authentication context. Learn more in [OAuth persistent grants cleanup](pf_oauth_persis_grants_cleanup.html). ## Configuring an AWS DynamoDB for persistent grant storage Set up an Amazon Web Services (AWS) *(tooltip: \
\

An Amazon subsidiary providing cloud computing platforms.\

\
)* DynamoDB so that PingFederate can store persistent grants in the DynamoDB NoSQL database. ### Before you begin Ensure that your server is configured to access DynamoDB. Learn more about configuring your server to access DynamoDB in [Setting up DynamoDB (web service)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SettingUp.DynamoWebService.html) in the AWS DynamoDB documentation. ### About this task PingFederate requires specific tables to store persistent grants on your DynamoDB server. Table-setup scripts are provided for this purpose. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingFederate supports the use of global multi-region tables for DynamoDB. However, these tables are managed entirely by AWS.Learn more about configuring global tables in [Amazon DynamoDB global tables](https://aws.amazon.com/dynamodb/global-tables/) in the DynamoDB documentation. | ### Steps 1. To create a table in DynamoDB to contain persistent grants, run the commands in the `/pingfederate/server/default/conf/access-grant/nosql-scripts/access-grant-dynamodb.txt` file. This file contains basic commands to create the table, with sample values for read and write throughput, as well as the command to enable `Expires` as the **Time-to-Live (TTL)** attribute. 1. (Optional) To rename the table and index names, edit the `table-name` and `\"IndexName\"` values in the table script in the `access-grant-dynamodb.txt` file. 2. Edit the `/pingfederate/server/default/conf/service-points.conf` file: 1. Locate the `AccessGrantManager` service point: ``` # Service for storage of access grants # Supported classes: # org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.oauth20.token.AccessGrantManagerLDAPADImpl : Use this service-point for a Microsoft Active Directory implementation. # org.sourceid.oauth20.token.AccessGrantManagerLDAPOracleImpl : Use this service-point for an Oracle Directory Server Enterprise Edition implementation. # org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDirectoryImpl : Use this service-point for a PingDirectory implementation. # org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDSImpl : Use this service-point for a PingDS implementation. # org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl : Use this service-point for an Amazon DynamoDB implementation. # access.grant.manager=org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl ``` 2. Update the value of the service point to `org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl`. 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 `access-grant-dynamodb.txt` file in step 1, edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl.xml` file to match your customized configuration. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you ran the script commands from the `access-grant-dynamodb.txt` and didn't change the default names in the commands, you don't need to edit the `/pingfederate/server/default/data/config-store/org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl.xml` file. | 1. Replace the `AccessGrantsClientId-index`, `AccessGrantsHashedRefreshToken-index`, `AccessGrantsUniqueUserIdClientId-index` 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.token.AccessGrantManagerDynamoDBImpl.xml` file. **DynamoDB Session Storage Manager Variables** | Variable | Description | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AccessGrantsClientId-index` | The name of the client ID index.This is the default value. | | `AccessGrantsHashedRefreshToken-index` | The name of the hashed refresh token index.This is the default value. | | `AccessGrantsUniqueUserIdClientId-index` | The name of the Unique User ID Client ID index.This is the default value. | | `EndpointOverride` | An optional endpoint URL which shouldn't 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;`. Learn more in [DynamoDB local usage notes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html) in the DynamoDB documentation. | | `maxPersistentGrants` | The maximum number of persistent grants allowed to store in DynamoDB per user, client and grant type, and authentication context qualifier.Setting this to a value less than or equal to 0 will turn off this limit. The default value is 100. | | `dynamoDbBatchSize` | Number of records to request when performing batch operations against DynamoDB. The minimum allowed value is 1, 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 10,000. | | `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. | 4. Start or restart the PingFederate service. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 active the change. | ### Result PingFederate relies on the DynamoDB TTL attribute to remove expired persistent grants from the database. You can find more information on TTL in [Expiring items by using DynamoDB Time to Live (TTL)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) in the DynamoDB documentation. ## Related links * [Configuring a JDBC connection](pf_configuring_jdbc_connection.html) * [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html)