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 Detail

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

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