Package org.sourceid.saml20.service.session.data

Interface SessionStorageManager

All Known Implementing Classes:
AbstractSessionStorageManagerImpl
public interface SessionStorageManager
This is the interface that must be implemented in order to store persistent authentication sessions. Plugins should not call this interface directly. The interface is only exposed in the SDK so that custom session storage implementations can be developed. Instead of directly implementing this interface, it is recommended to inherit from the AbstractSessionStorageManagerImpl base class. This will ensure that the storage manager class inherits the default implementation when new methods are added to this interface.

In order to be used at runtime, the custom storage manager class must be registered in the session.storage.manager entry of PingFederate's '<PF_INSTALL>/pingfederate/server/default/conf/service-points.conf' file.

Two classes are used to hold the data for persistent authentication sessions. SessionGroupData holds data for a group of authentication sessions within a single browser instance. Associated with each group are multiple AuthnSessionData objects, each containing the stored end user attributes for a specific authentication source (IdP adapter or IdP connection).

It is important to understand the role of various IDs in persistent session storage.

  • The session group ID is a static, unchanging ID for a session group.
  • The hashed session ID is a hash of the cookie value in the end user's browser. To prevent session fixation attacks, this cookie value changes when new authentication sessions are saved. As a result, the hashed session ID also changes. When this happens, the updateSessionGroup(SessionGroupData) method will be invoked with the previous and new values for the hashed session ID.
  • The unique user ID is a string uniquely identifying a given user within the deployment.

A session group ID always corresponds to just a single session group, and the same is true for a hashed session ID. However, a unique user ID may be associated with multiple session groups (corresponding to different browser instances). In addition, multiple user IDs may be associated with the same session group (for example, if a user has signed on in the same browser with different usernames).

The storage manager must support efficient retrieval of session groups and associated authentication sessions through three lookup keys: session group ID, hashed session ID, and unique user ID. For cleanup purposes, the storage manager should also support efficient removal of all session groups whose expiry time is earlier than the current time.

The storage implementation must also support efficient lookup and removal of all authentication sessions for a given session group ID.
Since:
10.3

  • Method Details

    • createSessionGroup

      void createSessionGroup(SessionGroupData sessionGroupData) throws SessionStorageException
      Save a new session group.
      Parameters:
      sessionGroupData - The data for the new session group.
      Throws:
      SessionStorageException - If an error occurs while saving the session group.

    • updateSessionGroup

      void updateSessionGroup(SessionGroupData sessionGroupData) throws SessionStorageException
      Update an existing session group. The SessionGroupData.getPrevHashedSessionId() value should be used as the lookup key. Note that the lookup key may have to be changed as part of this method. The new lookup key is provided via SessionGroupData.getHashedSessionId().
      Parameters:
      sessionGroupData - The updated session group data to be stored.
      Throws:
      SessionStorageException - If an error occurs while updating the session group.

    • deleteSessionGroups

      void deleteSessionGroups(Collection<String> hashedSessionIds) throws SessionStorageException
      Delete the session groups identified by the specified hashed session IDs. This method is responsible for also deleting all authentication sessions associated with these groups.
      Parameters:
      hashedSessionIds - The hashed session IDs of the groups to be deleted.
      Throws:
      SessionStorageException - If an error occurs while deleting the session groups.

    • deleteSessionGroupsByGroupIds

      void deleteSessionGroupsByGroupIds(Collection<String> sessionGroupIds) throws SessionStorageException
      Delete the session groups with the specified IDs. This method is responsible for also deleting all authentication sessions associated with these groups.
      Parameters:
      sessionGroupIds - The IDs of the session groups to be deleted.
      Throws:
      SessionStorageException - If an error occurs while deleting the session groups.

    • getSessionGroupsAndSessions

      Collection<SessionGroupAndSessionsData> getSessionGroupsAndSessions(Collection<String> hashedSessionIds) throws SessionStorageException
      For the specified hashed session IDs, retrieve session group data as well as data for all associated authentication sessions.
      Parameters:
      hashedSessionIds - The hashed session IDs for the session groups requested.
      Returns:
      The session groups and sessions data.
      Throws:
      SessionStorageException - If an error occurs while retrieving data for the specified hashed session IDs.

    • getSessionGroupsAndSessionsByGroupIds

      Collection<SessionGroupAndSessionsData> getSessionGroupsAndSessionsByGroupIds(Collection<String> sessionGroupIds) throws SessionStorageException
      For the specified session group IDs, retrieve session group data as well as data for all associated authentication sessions.
      Parameters:
      sessionGroupIds - The IDs for the session groups requested.
      Returns:
      The session groups and sessions data.
      Throws:
      SessionStorageException - If an error occurs while retrieving data for the specified session group IDs

    • getSessionGroupsByUniqueUserId

      Collection<SessionGroupData> getSessionGroupsByUniqueUserId(String uniqueUserId) throws SessionStorageException
      Retrieve data for all session groups associated with the specified unique user ID.
      Parameters:
      uniqueUserId - The unique user ID whose session groups will be retrieved
      Returns:
      Data for all session groups associated with the specified user ID.
      Throws:
      SessionStorageException - If an error occurs while retrieving session group data for the specified unique user ID.

    • saveAuthnSessions

      void saveAuthnSessions(Collection<AuthnSessionData> sessionDatas) throws SessionStorageException
      Save the specified authentication session data objects. An authentication session may already be stored with the same values for AuthnSessionData.getSessionGroupId() and AuthnSessionData.getAttributeHash(). If so, the implementation must ensure that the existing authentication session is removed and replaced with the new session.
      Parameters:
      sessionDatas - The authentication session data objects to save.
      Throws:
      SessionStorageException - If an error occurs while saving authentication session data.

    • deleteAuthnSessions

      void deleteAuthnSessions(String sessionGroupId, Collection<String> attributeHashes) throws SessionStorageException
      Delete authentication sessions for the specified session group ID and attribute hash values.
      Parameters:
      sessionGroupId - The session group ID that the authentication sessions belong to.
      attributeHashes - The attribute hash values for the authentication sessions to be deleted.
      Throws:
      SessionStorageException - If an error occurs while deleting the specified authentication sessions.

    • addUniqueUserId

      void addUniqueUserId(String sessionGroupId, String uniqueUserId) throws SessionStorageException
      Associate a unique user ID with a specified session group.
      Parameters:
      sessionGroupId - The ID of the session group.
      uniqueUserId - The unique user ID.
      Throws:
      SessionStorageException - If an error occurred while linking the specified unique user ID to the specified session group.

    • supportsBatchCleanup

      boolean supportsBatchCleanup()
      Indicates whether the storage implementation supports the deleteExpiredSessionGroups() method. If this method returns true, a background thread will periodically call deleteExpiredSessionGroups() to cleanup expired session groups. Note that this background thread only runs on the PingFederate admin console. The period between cleanup cycles is configurable in the file timer-intervals.xml. Storage managers are free to return false from this method and implement their own mechanism for cleaning up expired session groups and associated authentication sessions. The SessionGroupData.getExpiryTimeMillis() method defines the expiry time for a session group.
      Returns:
      True to ensure that the deleteExpiredSessionGroups() method is periodically called by a background thread, false otherwise.

    • deleteExpiredSessionGroups

      void deleteExpiredSessionGroups() throws SessionStorageException
      If supportsBatchCleanup() returns true, this method is periodically called by the PingFederate admin console to cleanup expired session groups and associated authentication sessions. This method should attempt to remove all expired session groups and associated authentication sessions. The SessionGroupData.getExpiryTimeMillis() method defines the expiration time for a session group. The storage implementation should ensure that all session groups with expiration time earlier than the current time can be deleted efficiently, without having to search through all saved session groups.
      Throws:
      SessionStorageException - If an error occurs while deleting expired session groups.

    • isDataSourceInUse

      boolean isDataSourceInUse(String datasourceId)
      Determine whether the storage implementation makes use of the specified PingFederate data source ID. Most custom storage implementations will return false.
      Parameters:
      datasourceId - The ID of a PingFederate data source.
      Returns:
      True if the implementation makes use of the specified data source, false otherwise.