PingFederate Server

Manage externally stored authentication sessions

Authentication sessions control when previously authenticated users are redirected back to the authentication sources on subsequent requests for browser-based single sign-on (SSO) and PingFederate user-facing applications.

When you enable authentication sessions, PingFederate maintains session data in memory. PingFederate also supports maintaining session data both in memory and on an external storage. This optional capability allows your organization to support use cases where a longer session duration or a greater resilience against restarts of PingFederate and browsers is desired.

PingFederate supports storing persistent authentication sessions on a database server or a PingDirectory server. When stored on a database server, the default cleanup task removes expired authentication sessions once a day. If stored on a PingDirectory server, configure a cleanup plugin in PingDirectory to suit the needs of your organization.

Managing authentication sessions stored in the database

PingFederate uses a cleanup task to remove expired authentication sessions from the configured database once a day. The cleanup task determines whether a session can be removed by looking at the session’s expiration timestamp and the current time.

About this task

Any session that has an expiration timestamp older than the current time by a configurable offset is subject to removal. As needed, the cleanup task can look at the session’s last activity timestamp instead. The cleanup task removes 500 expired sessions at a time until all expired sessions are removed. If expired sessions are growing rapidly, you can optionally increase the frequency of the cleanup task.

Increasing the frequency of the cleanup task or the number of expired sessions to be removed per batch (or both) adds more workload to your storage server. Make changes gradually to observe the impact.

In a clustered PingFederate environment, the cleanup task runs only on the console node. If adjustments are required, make them on the console node. No changes are required on any of the engine nodes.

Steps

  1. (Optional) Adjust the frequency of the cleanup task.

    1. Edit the <pf_install>/pingfederate/server/default/data/config-store/timer-intervals.xml file.

    2. Update the StoredSessionCleanerInterval value, in milliseconds.

      The default value is 86400000, which is 24 hours.

    3. Save your changes.

  2. (Optional) Configure other cleanup options.

    1. Edit the <pf_install>/pingfederate/server/default/data/config-store/org.sourceid.saml20.service.session.data.impl.SessionStorageManagerJdbcImpl.xml file.

      See the following table for more information about each field.

      Field Description

      ExpiredSessionGroupBatchSize

      The number of expired authentication sessions to be removed per batch.

      The default value is 500.

      ExpirationTimeColumnName

      The column of which its value determines whether an authentication session has expired in the context of the cleanup task. Valid options are expiry_time and last_activity_time.

      expiry_time

      Set to expiry_time if the cleanup task should only remove persistent authentication sessions that have expired.The cleanup task determines if a session can be removed by looking at the session’s expiration timestamp and the current time. If the expiration timestamp is older than the current time by the number of minutes specified by the ExpirationTimeOffsetMins field, the session is subject to removal.

      last_activity_time

      Set to last_activity_time if the clean task should remove persistent authentication sessions that have been left idle.The cleanup task determines if a session can be removed by looking at the session’s last activity timestamp and the current time. If the last activity timestamp is older than the current time by the number of minutes specified by the ExpirationTimeOffsetMins field, the session is subject to removal.For example, if PingFederate should remove persistent authentication sessions for which the last activity time is more than three weeks ago, set the ExpirationTimeColumnName value to last_activity_time and the ExpirationTimeOffsetMins value to 30240.

      The default value is expiry_time.

      ExpirationTimeOffsetMins

      The offset, in minutes, relative to the current time.

      The default value is 10.

    2. Save your changes.

  3. If you have made any changes, restart PingFederate.

    In a clustered PingFederate environment, you do not have to change or restart PingFederate on any of the engine nodes.

Managing authentication sessions stored in PingDirectory

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.

Steps

  1. Disable the PingFederate cleanup task.

    For a clustered PingFederate environment, make these changes on the console node. None of the engine nodes require any changes.

    1. Edit the <pf_install>/pingfederate/server/default/data/config-store/timer-intervals.xml file.

    2. Update the StoredSessionCleanerInterval value to 0.

    3. Save your changes.

    4. Restart PingFederate.

  2. Sign on to the PingDirectory administrative console.

  3. Go to Configuration > Plugin Root.

  4. On the Plugin Root window, click New Plugin, and then select Clean Up Expired PingFederate Persistent Sessions Plugin.

  5. Configure a new instance of the Clean Up Expired PingFederate Persistent Sessions Plugin.

    The following table contains information about each required field:

    Field Description

    Name

    The name of this plugin instance.

    Enabled

    Select the checkbox to enable this plugin instance. Clear the checkbox to disable this plugin instance.

    This checkbox is cleared by default.

    Expiration Offset

    The offset relative to the current time.

    Enter an integer to indicate the time value, followed by its unit of measurement.

    This field has no default value.

    Polling Interval

    The frequency with which to run this plugin.

    Enter an integer to indicate the time value, followed by its unit of measurement.

    This field has no default value.

    Max Updates Per Second

    This setting smooths out the performance impact on the server by throttling the purging to the specified maximum number of updates per second. To avoid a large backlog, set this value well above the average rate at which expired data is generated.

    This field has no default value.

    (Optional) Peer Server Priority Index

    In a clustered PingFederate environment, this parameter determines the relative priority for purging stored sessions based on the server’s cluster node index.

    Valid values are integers. If left blank, server priority is determined automatically.

    Num Delete Threads

    The number of threads dedicated to deleting stored sessions. The default value is 1.

    You can find more detailed description of these values in the Clean Up Expired PingFederate Persistent Sessions Plugin developer documentation.

  6. Click Save.