PingFederate Server

Configuring authentication sessions

Use the Sessions window to configure and override the default timeout limits for authentication sessions.

Steps

  1. Go to Authentication → Policies → Sessions.

  2. Optional: In the Sessions window, configure the global policy and timeout settings under Authentication Sessions. A screen capture of the authentication sessions window. There are check boxes for Enable authentication for all sources and hash unique user key value. There are list settings for Idle timeout and Max timeout.

    1. Select the Enable Sessions for All Authentication Sources check box if PingFederate should track authentication sessions for all authentication sources. Clear this check box if you prefer to enable authentication sessions for only a few authentication sources or disable authentication sessions altogether. This check box is not selected by default.

    2. If your use cases require longer sessions or greater resilience against restarts of PingFederate and browsers, select the Make Authentication Sessions Persistent check box.

      Selecting the check box causes the PF.PERSISTENT cookie to be set in the user’s browser. By default, this cookie persists across browser restarts. To allow for very long sessions, the expiration period for the cookie defaults to 94608000 seconds, or 3 years. You can change this period in the cookie-max-age setting in the persistent-session-cookie-config.xml file. If you prefer to have the PF.PERSISTENT cookie cleared on browser exit, set cookie-max-age to -1. Regardless of the cookie’s expiration period, PingFederate always enforces the configured session timeouts. However a user might lose their session earlier if the PF.PERSISTENT cookie expires or is removed by the browser.

      Persistent authentication sessions require an external storage.

      Your authentication session adapters should use either all persistent or all non-persistent sessions.

      Mixing usage can lead to undesired results, like non-persistent sessions being retained even after the session cookies clear on quitting the browser.

      You should use JWT-based persistent session cookies. You can configure this using the cookie-format parameter in the persistent-session-cookie-config.xml file. JWT-based cookies are the default setting.

      JWT-based cookies improve security by allowing PingFederate to restore missing session information from the PF.PERSISTENT cookie rather than looking up session data from external persistent session storage.

      As of version 9.3, PingFederate alleviates DoS attacks by protecting the persistent session process. It does this by treating repeated persistent cookies that do not have a PF cookie as a replay if repeated in a specified time. This time is set to 300 seconds by default, and you can change it by modifying EmptySessionReplayRetentionsSecs in the <pf-install>/server/default/data/config-store/org.sourceid.saml20.service.session.StoredSessionServiceImpl.xml file.

      For example:

      • If a request arrives with a PF.PERSISTENT cookie and without a PF cookie, PingFederate starts counting the time set in EmptySessionReplayRetentionsSecs.

      • If another request arrives with the same PF.PERSISTENT cookie and without a PF cookie within the time specified in the configuration file, PingFederate treats it as a replayed request and does not perform a database lookup.

      You can disable this behavior by setting EmptySessionReplayRetentionsSecs to 0.

    3. Select the Hash Unique User Key Value check box if you want the unique user key to be hashed using SHA-256. When this option is enabled, PingFederate associates this hashed value with the particular user’s authentication sessions.

      The hashed value is used for features related to unique user keys; for example, the HTML Form Adapter’s Revoke Sessions After Password Change or Reset option (for more information, see Configuring an HTML Form Adapter instance). The hashed value will be visible in server and audit logs, and in session storage if Make Authentication Sessions Persistent is enabled.

    4. Optional: Override the default timeout values for all authentication sources.

      Field Description

      Idle Timeout

      Modify the default inactivity timeout value in the Idle Timeout field and select a unit of measurement from the list.

      You can enter an integer that represents a time period between 1 minute and 1,095 days. You can also empty the value to indicate that the inactivity timeout value should match the maximum lifetime.

      The default inactivity timeout value is 60 minutes.

      Max Timeout

      Modify the default maximum lifetime of an authentication session in the Max Timeout field and select a unit of measurement from the list.

      You can enter an integer that represents a time period between 1 minute and 1,095 days. You can also empty the value to indicate that the authentication sessions do not expire until they are removed from the system.

      The value of the Max Timeout field cannot be less than that of the Idle Timeout field.

      The default maximum timeout value is 480 minutes (eight hours).

  3. Optional: Configure policy and settings for individual authentication sources in the Overrides section.

    A screen capture of the Overrides section in the Authentication Sessions window configuration. There are fields for authentication source, enable sessions, user device type, persistent, override timeouts, idle timeout, max timeout, units, authentication context sensitive, and action.

    1. In the Authentication Source list, select an identity provider (IdP) adapter instance or an IdP connection.

    2. Configure individual policy for the selected authentication source as follows:

      Global policy (underAuthentication Sessions) Individual policy (underOverrides)

      The Enable Sessions for All Authentication Sources check box is not selected.

      Authentication-session tracking is not enabled for all authentication sources.

      Select the Enable Sessions check box to enable authentication-session tracking for the selected authentication source.

      Select a User Device Type to specify the type of user device that will retain the session. For more information on user device types, see step 3c.

      The Enable Sessions for All Authentication Sources check box is selected.

      Authentication-session tracking is enabled for all authentication sources.

      Clear the Enable Sessions check box to disable authentication-session tracking for the selected authentication source.

      Select the Enable Sessions check box for the purpose of overriding other authentication-session settings for the selected authentication source.

      Select a User Device Type to specify the type of user device that will retain the session. For more information on user device types, see step 3c.

      The Enable Sessions check box is not selected by default.

    3. If This is my device is enabled for one or more HTML Form Adapter instances in the deployment, specify the User Device Type for the policy.

      For an HTML Form Adapter instance that has This is my device enabled:

      • If a user signs on without selecting the This is my device check box, the device type is Shared.

      • If a user signs on and selects the This is my device check box, the device type is Private.

      • A session is only retained if the policy’s User Device Type matches the device type indicated by the user’s selection.

        For more information on User Device Type values, see the table below.

        Only select a User Device Type if the Enable Sessions check box is selected and This is my device is enabled for one or more HTML Form Adapter instances in the deployment.

        • If you clear the Enable Sessions check box for an Authentication Source, no authentication sessions will be created for any device type.

        • If you select the global Enable Sessions for All Authentication Sources check box, the User Device Type defaults to Private for all authentication sources.

        • If This is my device isn’t enabled for one or more HTML Form Adapter instances in the deployment, leave the User Device Type as Private.

        You can create more than one session policy override for the same authentication source if the session policy overrides have different values for the User Device Type.
      User device type values
      Value Description

      Private (default)

      If you select Private as the User Device Type, PingFederate retains a session if either:

      • The user interacted with an HTML Form Adapter instance that had This is my device enabled and they selected the This is my device check box.

      • The user did not interact with an HTML Form Adapter instance that had This is my device enabled.

      Shared

      If you select Shared as the User Device Type, PingFederate retains a session only if the user interacted with an HTML Form Adapter instance that had This is my device enabled and did not select the This is my device check box.

      Any

      If you select Any as the User Device Type, PingFederate always retains an authentication session for the source.

    4. Select the Persistent check box if your use cases require a longer session duration or a greater resilience against restarts of PingFederate and browsers.

      Available and applicable only if the Enable Sessions check box is selected. The Persistent check box is not selected by default.

      Persistent authentication sessions require an external storage.

      Notes under step 2b apply here as well.

    5. If authentication-session tracking is enabled for the selected authentication source and if you want to configure specific timeout values, select the Override Timeouts check box and configure timeout settings.

      Field Description

      Idle Timeout

      You can enter an integer that represents a time period between 1 minute and 1095 days. You can also empty the value to indicate that the inactivity timeout value should match the maximum lifetime.

      This field has no default value.

      Max Timeout

      You can enter an integer that represents a time period between 1 minute and 1095 days. You can also empty the value to indicate that the authentication sessions do not expire until they are removed from the system.

      The value of the Max Timeout field cannot be less than that of the Idle Timeout field.

      This field has no default value.

      Unit

      Select from the list the unit of measurement for both the Idle Timeout and Max Timeout fields.

      The default selection is Minutes.

    6. If authentication-session tracking is enabled for the selected authentication source and if you want to enforce authentication requirement based on the authentication context for the selected authentication source, select the Authentication Context Sensitive check box. This check box is not selected by default.

    7. Click Add.

    8. Repeat these steps to configure individual policy and settings for additional authentication sources.

      Click Edit, Update, or Cancel to make or undo a change to an existing entry. Click Delete or Undelete to remove an existing entry or cancel the removal request.

  4. To save your configuration changes, click Save.

Result

When PingFederate authentication sessions are enabled, you can configure session-validation options for your OAuth use cases. These optional settings enable you to conjoin the validity of access tokens and the authentication sessions of the users. For more information, see Managing session validation settings.