PingFederate Server

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 <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl.xml file and the <pf_install>/pingfederate/server/default/conf/service-points.conf file.

Steps

  1. Run the table-setup scripts for your database server provided in the <pf_install>/pingfederate/server/default/conf/access-grant/sql-scripts directory.

  2. If you have not already done so, create a JDBC data store for your database server on System > Data & Credential Stores > Data Stores.

  3. Copy the System ID of the applicable Java Database Connection (JDBC) data store from the Data Stores window.

  4. Edit the <pf_install>/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 <c:item name="PingFederateDSJNDIName"/> 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 version="1.0" encoding="UTF-8"?>
<c:config xmlns:c="http://www.sourceid.org/2004/05/config">
    <c:item name="PingFederateDSJNDIName">JDBC-123456789ABCDEF123456789ABCDEF123456A0A6</c:item>
</c:config>

  5. Edit the <pf_install>/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.

Configuring an AWS DynamoDB for persistent grant storage

Set up an Amazon Web Services (AWS) DynamoDB so that PingFederate can store persistent grants in the DynamoDB NoSQL database.

Before you begin

Make sure that your server is configured to access DynamoDB.

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 in the DynamoDB documentation.

Steps

  1. To create a table in DynamoDB to contain persistent grants, run the commands in the <pf_install>/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 <pf_install>/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 <pf_install>/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 <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl.xml file.

    1. Replace the <c:item name="AccessGrantsClientIdIndex">AccessGrantsClientId-index</c:item>, <c:item name="AccessGrantsHashedRefreshTokenIndex">AccessGrantsHashedRefreshToken-index</c:item>, <c:item name="AccessGrantsUniqueUserIdClientIdIndex">AccessGrantsUniqueUserIdClientId-index</c:item> 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 <pf_install>/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 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, <c:item name="EndpointOverride">http://localhost:8000</c:item>;. Learn more in DynamoDB local usage notes in the DynamoDB documentation.

    maxPersistentGrants

    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) in the DynamoDB documentation.