--- title: Defining a datastore for persistent authentication sessions description: When enabling PingFederate authentication sessions, you can select the persistent option so that PingFederate can leverage previous sessions as users request protected resources after restarting their browsers. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_defining_datastore_persis_auth_sess canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_defining_datastore_persis_auth_sess.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: July 5, 2022 section_ids: about-this-task: About this task steps: Steps related-links: Related links configuring-an-external-database-for-authentication-sessions: Configuring an external database for authentication sessions about-this-task-2: About this task steps-2: Steps example: Example: result: Result related-links-2: Related links configuring-pingdirectory-for-authentication-sessions: Configuring PingDirectory for authentication sessions steps-3: Steps example-2: Example: related-links-3: Related links configuring-pingds-for-authentication-sessions: Configuring PingDS for authentication sessions steps-4: Steps example-3: Example: example-4: Example: example-5: Example: configuring-an-aws-dynamodb-for-persistent-authentication-sessions: Configuring an AWS DynamoDB for persistent authentication sessions before-you-begin: Before you begin about-this-task-3: About this task steps-5: Steps result-2: Result using-custom-solutions-for-persistent-session-storage: Using custom solutions for persistent session storage steps-6: Steps --- # Defining a datastore for persistent authentication sessions When enabling PingFederate authentication sessions, you can select the persistent option so that PingFederate can leverage previous sessions as users request protected resources after restarting their browsers. ## About this task This optional persistent configuration requires external storage of session-state data, as opposed to in-memory alone. By default, PingFederate uses its internal HSQLDB database to maintain persistent authentications. You can configure PingFederate to maintain persistent authentication sessions externally on a database server or a PingDirectory server. Also, the PingFederate SDK lets you use [custom solutions for persistent session storage](#_using_custom_solutions_for_persistent_session_storage). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 might cause various problems due to its limitations and HSQLDB involved cases are not supported by Ping Identity. | ## Steps 1. Create the required data structure on the external storage medium. 2. Modify two PingFederate configuration XML files. ## Related links * [Sessions](pf_sessions.html) * [About Server Clustering](../server_clustering_guide/pf_server_clustering_guide.html) ## Configuring an external database for authentication sessions Set up various tables so that PingFederate can store authentication sessions on corresponding database servers. ### About this task Specific tables are required in order for PingFederate to store authentication sessions on your database server. Table-setup scripts are provided for supported database servers. ### Steps 1. Run the table-setup scripts, provided in the `/pingfederate/server/default/conf/authentication-session/sql-scripts` directory, for your database server. 2. If you have not already done so, go to **System > Data & Credential Stores**. In the **Data Stores** window, create a Java Database Connection (JDBC) datastore for your database server. 3. Copy the system ID of the applicable JDBC datastore from the **Data Stores** window. 4. Edit the `org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl.xml` file, located in the `/pingfederate/server/default/data/config-store` directory. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 data store connection and save the file. ### Example: For example, if the system ID is `JDBC-123456789ABCDEF123456789ABCDEF123456A0A6`, update the `org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl.xml` file as follows. ```xml JDBC-123456789ABCDEF123456789ABCDEF123456A0A6 ``` 5. Edit the `/pingfederate/server/default/conf/service-points.conf` file. For example, if the system ID is `SessionStorageManager`: 1. Go to the `# Service for storing Authentication Sessions` section. ``` # Service for storing Authentication Sessions. # Supported classes: # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation. session.storage.manager=org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl ``` 2. Validate that the value of the `session.storage.manager` service is `org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl`, the default value. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 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 activate the change. | ### Result PingFederate removes expired authentication sessions from the database once a day. To fine-tune the frequency and the number of expired authentication sessions to remove, refer to [Managing authentication sessions stored in the database](pf_managing_externally_stored_authentication_sessions.html#managing_authentication_sessions_stored_in_database). ### Related links * [Configuring a JDBC connection](pf_configuring_jdbc_connection.html) * [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html) ## Configuring PingDirectory for authentication sessions Use specific schema objects to enable PingFederate to store authentication sessions on your directory server. For PingDirectory, LDIF scripts are provided for this purpose. ### Steps 1. Update the LDAP schema. 1. Sign on to the PingDirectory administrative console. 2. Go to **LDAP Schema > Schema Utilities**. 3. Click **Import Schema Element**. 4. Copy the schema changes from the `authentication-session-attributes-ldap-pingdirectory.ldif` file and paste them into the text area. The file is located in the `/pingfederate/server/default/conf/authentication-session/ldif-scripts` directory. Replace the placeholder values with relevant information from your directory server. 1. Click **Import**. 2. Create the following indexes. | Attribute name | Index type | | ------------------------------------------- | ---------- | | `pf-authn-session-group-hashed-session-id` | equality | | `pf-authn-session-group-user-ids` | equality | | `pf-authn-session-group-expiry-time` | ordering | | `pf-authn-session-group-last-activity-time` | ordering | Create these indexes with PingDirectory's `dsconfig` utility. The `dsconfig` utility is interactive. You can also provide inputs as command arguments. The following examples create the indexes. ```shell $ bin/dsconfig create-local-db-index \ --backend-name userRoot \ --index-name pf-authn-session-group-hashed-session-id \ --set index-type:equality ``` ```shell $ bin/dsconfig create-local-db-index \ --backend-name userRoot \ --index-name pf-authn-session-group-user-ids \ --set index-type:equality ``` ```shell $ bin/dsconfig create-local-db-index \ --backend-name userRoot \ --index-name pf-authn-session-group-expiry-time \ --set index-type:ordering ``` ```shell $ bin/dsconfig create-local-db-index \ --backend-name userRoot \ --index-name pf-authn-session-group-last-activity-time \ --set index-type:ordering ``` After adding the indexes, use the `rebuild-index` utility to build the indexes. The following example builds the required indexes. ```shell $ bin/rebuild-index \ --baseDN "dc=example,dc=com" \ --index pf-authn-session-group-hashed-session-id \ --index pf-authn-session-group-user-ids \ --index pf-authn-session-group-expiry-time \ --index pf-authn-session-group-last-activity-time ``` Learn more in [Working with indexes](https://docs.pingidentity.com/pingdirectory/latest/pingdirectory_server_administration_guide/pd_ds_work_with_indexes.html) in the PingDirectory documentation. 3. If you have not already done so, create an LDAP data store for your directory server on **System > Data & Credential Stores > Data Stores**. 4. Copy the system ID of the applicable LDAP data store from the **Data Stores** window. 5. Edit the `/pingfederate/server/default/data/config-store/org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl.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. ### Example: For example, if the system ID is `LDAP-123456789ABCDEF123456789ABCDEF123456A0AC`, update the configuration file as follows. ``` ... LDAP-123456789ABCDEF123456789ABCDEF123456A0AC ... ``` 2. Enter a value for the `` element. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This is the distinguished name (DN) that points to the client location. For more information, see the inline comment and the LDIF scripts in the `/pingfederate/server/default/conf/authentication-session/ldif-scripts` directory. | 3. Update the attribute names only if you have changed attribute names in the LDIF scripts located in the `/pingfederate/server/default/conf/authentication-session/ldif-scripts` directory. 4. Save the file. 6. Edit the `/pingfederate/server/default/conf/service-points.conf` file. 1. Go to the `# Service for storing Authentication Sessions` section. ``` # Service for storing Authentication Sessions. # Supported classes: # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation. session.storage.manager=org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl ``` 2. Change the value of the `session.storage.manager` service to `org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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. | 7. 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 activate the change. | | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When storing persistent authentication sessions on a PingDirectory server, you must also configure a cleanup plugin in PingDirectory to remove expired authentication sessions from your directory server. Learn more in [Managing authentication sessions stored in PingDirectory](pf_managing_externally_stored_authentication_sessions.html#managing_authentication_sessions_stored_in_pd). | ### Related links * [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html) * [Installing the Server](https://docs.pingidentity.com/pingdirectory/latest/installing_the_pingdirectory_suite_of_products/pd_suite_installing_the_servers.html) * [Using the schema editor utilities](https://docs.pingidentity.com/pingdirectory/latest/pingdirectory_server_administration_guide/pd_ds_schema_editor_utilities.html) * [Working with indexes](https://docs.pingidentity.com/pingdirectory/10.3/pingdirectory_server_administration_guide/pd_ds_work_with_indexes.html) * [Configuring an LDAP connection](help_datasourcetasklet_ldapconfigstate.html) ## Configuring PingDS for authentication sessions You can use LDIF scripts to enable PingFederate to store authentication sessions in PingDS. ## Steps 1. Update the LDAP schema: 1. Create a copy of the ` Data & Credential Stores > Data Stores**. 5. Copy the system ID of the applicable LDAP data store from the **Data Stores** window. 6. Edit the `/pingfederate/server/default/data/config-store/org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl.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. ### Example: For example, if the system ID is `LDAP-123456789ABCDEF123456789ABCDEF123456A0AC`, update the configuration file as follows. ``` ... LDAP-123456789ABCDEF123456789ABCDEF123456A0AC ... ``` 2. Enter a value for the `` element. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This is the distinguished name (DN) that points to the client location. For more information, see the inline comment and the LDIF scripts in the `/pingfederate/server/default/conf/authentication-session/ldif-scripts` directory. | 3. Update the attribute names only if you have changed attribute names in the LDIF scripts located in the `/pingfederate/server/default/conf/authentication-session/ldif-scripts` directory. 4. Save the file. 7. Edit the `/pingfederate/server/default/conf/service-points.conf` file. 1. Go to the `# Service for storing Authentication Sessions` section. ``` # Service for storing Authentication Sessions. # Supported classes: # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation. session.storage.manager=org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl ``` 2. Change the value of the `session.storage.manager` service to `org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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. | 8. 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 activate the change. | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When storing persistent authentication sessions on a PingDS server, you must also configure TTL settings in PingDS to remove expired authentication sessions from your directory server. Learn more in [Managing authentication sessions stored in PingDS](pf_managing_externally_stored_authentication_sessions.html#managing_authentication_sessions_stored_in_ds). | ## Configuring an AWS DynamoDB for persistent authentication sessions Set up an Amazon Web Services (AWS) *(tooltip: \
\

An Amazon subsidiary providing cloud computing platforms.\

\
)* DynamoDB so that PingFederate can store persistent authentication sessions 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 persistent authentication sessions 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 AWS documentation. | ### Steps 1. To create a table in DynamoDB to contain authentication sessions, run the commands in the `/pingfederate/server/default/conf/authentication-session/nosql-scripts/authentication-session-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 `ExpiryTime` 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 `authentication-session-dynamodb.txt` file. 2. (Optional) If authentication sessions are not already enabled in PingFederate, go to **Authentication > Policies > Sessions** to configure them. For more information, see [Configuring authentication sessions](pf_config_auth_sessions.html). 3. Edit the `/pingfederate/server/default/conf/service-points.conf` file: 1. Locate the `SessionStorageManager` service point: ``` # Service for storing Authentication Sessions. # Supported classes: # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation. session.storage.manager=org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl ``` 2. Update the value of the service point to `org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl`. 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. | 4. (Optional) If you modified the default table and index names in the `authentication-session-dynamodb.txt` file in step 1, edit the `/pingfederate/server/default/data/config-store/org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl.xml` file to match your customized configuration. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you ran the script commands from the `authentication-session-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.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl.xml` file. | 1. Replace the ``, ``, ``, `` 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.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl.xml` file. **DynamoDB Session Storage Manager Variables** | Variable | Description | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PingFederateAuthenticationSessionHashedSessionId-index` | The name of the hashed session ID index.This is the default value. | | `PingFederateAuthenticationSessionUserIdGroupId-index` | The name of the user ID and group 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, `http://localhost:8000`. For more information, see [DynamoDB local usage notes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html) in the AWS 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. | 5. 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. | ### Result PingFederate relies on the DynamoDB TTL attribute to remove expired authentication sessions from the database. For more information on TTL, see [Expiring items by using DynamoDB Time to Live (TTL)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) in the AWS DynamoDB documentation. ## Using custom solutions for persistent session storage The PingFederate SDK supports custom storage for persistent authentication sessions. ## Steps 1. Implement the `SessionStorageManager` interface. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For more information, see the Javadoc for the `SessionStorageManager` interface. The Javadocs for PingFederate are in the `/pingfederate/sdk` directory. | 2. Edit the `/pingfederate/server/default/conf/service-points.conf` file: 1. Go to the `# Service for storing Authentication Sessions` section. ``` # Service for storing Authentication Sessions. # Supported classes: # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl : Use this service-point for a Jdbc implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerLdapImpl : Use this service-point for an LDAP implementation. # org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl : Use this service-point for a DynamoDB implementation. session.storage.manager=org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl ``` 2. Change the value of the `session.storage.manager` service to the name of your class. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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. Deploy the required program files of your custom implementation to all PingFederate servers. 4. 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. |