PingFederate Server

Configuring external databases for scope storage

Specific tables are required in order for PingFederate to store scopes, the associated attributes, and their values (if any), on your database server. Table-setup scripts are provided for supported database servers.

Configuring an AWS DynamoDB for OAuth scope storage

You can configure PingFederate to manage OAuth scopes externally using an Amazon Web Services (AWS) DynamoDB. You can learn more about setting up your AWS DynamoDB in Configuring an AWS DynamoDB datastore.

Steps

  1. To create a table in DynamoDB to contain scopes, run the commands in the <pf_install>/pingfederate/server/default/conf/oauth-scope-management/nosql-scripts/oauth-scope-management-dynamodb.txt file.

    This file contains basic commands to create the table, with sample values for read and write throughout, as well as the command to add the default scope to the table.

    You must add the default scope. If you don’t add a default scope, PingFederate will stop working.

    1. (Optional) To rename the table and index names, edit the table-name and \"IndexName\" values in the table script in the oauth-scope-management-dynamodb.txt file before running the script.

  2. Edit the <pf_install>/pingfederate/server/default/conf/service-points.conf file.

    1. In the ScopeManager service point, set the scope.manager value to org.sourceid.oauth20.domain.ScopeManagerDynamoDBImpl.

    2. Save and close the file.

    3. In a clustered PingFederate environment, repeat these steps for each node in the cluster.

  3. (Optional) If you modified the default table and index names in the oauth-scope-management-dynamodb.txt file in the first step, edit the <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.ScopeManagerDynamoDBImpl.xml file to match your customized configuration.

    If you ran the script commands from the oauth-scope-management-dynamodb.txt and didn’t change the default names in the commands, you don’t need to edit the org.sourceid.oauth20.domain.ScopeManagerDynamoDBImpl.xml file.

    1. Replace the <c:item name="ScopesTableName">PingFederateOAuthScopes</c:item> and <c:item name="TypeIndex">PingFederateOAuthScopesType-index</c:item> element values with the customized names created during your initial DynamoDB setup.

    2. Save and close the file.

      The following table describes the default PingFederate variables in the <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.oauth20.domain.ScopeManagerDynamoDBImpl.xml file.

    DynamoDB Scope Manager Variables
    Variable Description

    PingFederateOAuthScopes

    The name of the scope table.

    This is the default value.

    PingFederateOAuthScopesType-index

    The name of the scope/scope group type 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.

    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.

    cacheExpirySecs

    Cache expiration (in seconds) for OAuth scopes and scope groups retrieved from DynamoDB. After this period, the cached entry is invalidated and refetched. The default value is 60.

  4. Start or restart PingFederate.

  5. For a clustered PingFederate environment, replicate this new configuration to other engine nodes in System > Server > Cluster Management.

You can optionally add the <c::item name="cacheExpirySecs"></c::item> parameter to the org.sourceid.oauth20.domain.ScopeManagerDynamoDBImpl.xml file that sets how long, in seconds, values fetched from DynamoDB are retained in the cache.