--- title: Configuring authentication sessions description: Use the Sessions window to configure and override the default timeout limits for authentication sessions. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_config_auth_sessions canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_config_auth_sessions.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: August 26, 2024 section_ids: steps: Steps result: Result related-links: Related links --- # 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 checkboxes for Enable authentication for all sources and hash unique user key value. There are list settings for Idle timeout and Max timeout.](_images/skd1655847366399.png) 1. Select the **Enable Sessions for All Authentication Sources** checkbox if PingFederate should track authentication sessions for all authentication sources. Clear this checkbox if you prefer to enable authentication sessions for only a few authentication sources or disable authentication sessions altogether. This checkbox 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** checkbox. Selecting the checkbox 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 `/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** checkbox 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](pf_config_html_form_adapt_instance.html)). 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.](_images/vre1637088217060.png) 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** checkbox is not selected.Authentication-session tracking is not enabled for all authentication sources. | Select the **Enable Sessions** checkbox 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** checkbox is selected.Authentication-session tracking is enabled for all authentication sources. | Clear the **Enable Sessions** checkbox to disable authentication-session tracking for the selected authentication source.Select the **Enable Sessions** checkbox 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** checkbox 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** checkbox, the device type is **Shared**. * If a user signs on and selects the **This is my device** checkbox, 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** checkbox 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** checkbox 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** checkbox, 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** checkbox. - 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** checkbox. | | **Any** | If you select **Any** as the **User Device Type**, PingFederate always retains an authentication session for the source. | 4. Select the **Persistent** checkbox 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** checkbox is selected. The **Persistent** checkbox 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** checkbox 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** checkbox. This checkbox 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 *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* 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](help_beareraccesstokenmgmtplugintasklet_sessionvalidationstate.html). ## Related links * [Defining a datastore for persistent authentication sessions](pf_defining_datastore_persis_auth_sess.html) * [Configuring an HTML Form Adapter instance](pf_config_html_form_adapt_instance.html)