PingFederate Server

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.

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.

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 <pf_install>/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 <pf_install>/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 <c:item name="PingFederateDSJNDIName"/> 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 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.

    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. Change the value of the session.storage.manager service to com.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.

    include:::partial$pf_rc_notes.adoc[tags=pf_ph_replicateConfiguration] 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, see Managing authentication sessions stored in the database.

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 <pf_install>/pingfederate/server/default/conf/authentication-session/ldif-scripts directory.

      Replace the placeholder values with relevant information from your directory server.

    5. 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.

    $ bin/dsconfig create-local-db-index \
  --backend-name userRoot \
  --index-name  pf-authn-session-group-hashed-session-id  \
  --set index-type:equality
    $ bin/dsconfig create-local-db-index \
  --backend-name userRoot \
  --index-name  pf-authn-session-group-user-ids  \
  --set index-type:equality
    $ bin/dsconfig create-local-db-index \
  --backend-name userRoot \
  --index-name  pf-authn-session-group-expiry-time  \
  --set index-type:ordering
    $ 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.

    $ 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

    For more information, see Working with Indexes in the PingDirectory Administration Guide.

  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 <c:item name="PingFederateDSJNDIName"/> 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.

      ...
<!-- Data store id -->
<c:item name="PingFederateDSJNDIName">LDAP-123456789ABCDEF123456789ABCDEF123456A0AC</c:item>
...

    2. Enter a value for the <c:item name="SearchBase"/> 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 <pf_install>/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 <pf_install>/pingfederate/server/default/conf/authentication-session/ldif-scripts directory.

    4. Save the file.

  6. Edit the <pf_install>/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. For more information, see Managing authentication sessions stored in PingDirectory.

Configuring an AWS DynamoDB for persistent authentication sessions

Set up an Amazon Web Services (AWS) 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 in the AWS documentation.

Steps

  1. To create a table in DynamoDB to contain authentication sessions, run the commands in the <pf_install>/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.

  3. Edit the <pf_install>/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 <pf_install>/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 <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.saml20.service.session.data.impl.SessionStorageManagerDynamoDBImpl.xml file.

    1. Replace the <c:item name="SessionGroupTableName"/>, <c:item name="UserIdTableName"/>, <c:item name="HashedSessionIdIndexName"/>, <c:item name="SessionUserIdGroupIdIndexName"/> 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.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, <c:item name="EndpointOverride">http://localhost:8000</c:item>;. For more information, see DynamoDB local usage notes 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) 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 <pf_install>/pingfederate/sdk directory.

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

    include:::partial$pf_rc_notes.adoc[tags=pf_ph_replicateConfiguration] Start or restart the PingFederate service on each engine node to activate the change.