PingAccess

Configuring advanced web session settings

Configure advanced settings on a web session for more control over how to set cookies, preserve requests, and more. These settings are optional.

Steps

  • In the Cookie Domain field, enter a valid domain where the cookie is stored, such as corp.yourcompany.com.

    If you set a cookie domain, all of your web resources must reside within that domain. If you do not set a cookie domain, the PingAccess token is recreated for each host domain where you access applications.

    Setting an invalid Cookie Domain causes authentication to fail. This results in PingAccess redirecting the user to reauthenticate with PingFederate indefinitely.

  • Select Secure Cookie to indicate that the PingAccess cookie must be sent through HTTPS connections only.

    This checkbox is selected by default.

    Selecting Secure Cookie in a non-HTTPS environment causes authentication to fail. This results in PingAccess redirecting the user to reauthenticate with PingFederate indefinitely.

  • Select HTTP-Only Cookie to enable the HttpOnly flag on cookies that contain the PingAccess token.

    This checkbox is selected by default.

    Cookies that have this flag aren’t accessible through the use of non-HTTP methods such as JavaScript calls (for example, referencing document.cookie), and cannot be easily stolen using cross-site scripting.

  • Select Partitioned Cookie to add the Partitioned attribute to all cookies that PingAccess sets for this web session.

    This checkbox is cleared by default.

    Selecting Partitioned Cookie ensures that cross-site cookies will continue to be readable within the same context that they’re created in. Learn more in PingAccess 8.1 (June 2024).

    Use the Partitioned Cookie checkbox to override the value of the pa.default.session.cookie.attributes.partitioned property in the run.properties file for this web session without needing to apply changes to all of the nodes in a PingAccess cluster and restart them.

  • Select Enable PKCE to prompt PingAccess to send a SHA256 code challenge and corresponding code verifier as a proof key for code exchange during the code authentication flow.

    This checkbox is selected by default.

  • In the SameSite Cookie list, select a level of restriction for when cookies can be sent in a cross-site request.

    Choose from:

    • Lax (default): The cookie should be sent on initial navigation to a site. It can be sent in same-site requests but not cross-site requests.

    • Strict: The cookie can’t be sent in top-level cross-site requests.

      The SameSite=Strict attribute provides greater protection against cross-site request forgery (CSRF), but cannot fully prevent it. Use the SameSite=Strict attribute as part of a more comprehensive CSRF protection strategy. Learn more in https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-14#section-8.8.

    • None: The cookie can be used across different sites without restriction.

      To prevent browser compatibility issues, if PingAccess detects that the user’s browser matches any of the values set in the pa.websession.cookie.sameSiteExcludedUserAgentPatterns property in the run.properties file, PingAccess doesn’t add the SameSite=None attribute to cookies.

    • Disabled: PingAccess does not set the SameSite attribute. The browser determines how to handle the cookie.

      A browser issue can prevent sign on if the SameSite Cookie attribute is set. Learn more in the PingAccess 7.0 SameSite cookie upgrade issue release note entry.

  • Enter any additional Scopes that you want to request from the OIDC token provider during the ID token request.

    If you have a token provider configured, you can select published scopes from the list based on the selected Client ID.

    To select unverified scopes, enter the scope and select Use unverified scope "[scopename]".

    You must configure the token provider to handle all of the scopes that you select, including any custom scope values.

    Users can access all attributes by examining browser traces. Although they are integrity protected to prevent changes, sensitive or confidential attributes can still be viewed if the user decodes the ID Token’s value.

  • In the Prompt Parameter list, select one of the following to let the authorization server know whether to prompt an end user to reauthenticate or provide consent.

    Choose from:

    • none: Returns an error if the end user isn’t authenticated or if the OAuth client doesn’t have user consent for the requested claims. If selected, the authorization server doesn’t prompt the end user with a consent or authentication page.

    • login: The authorization server prompts the end user to reauthenticate. If the end user doesn’t reauthenticate successfully, it returns an error.

      For extra security, PingAccess validates the <auth_time> the login request was sent at against the <auth_time> the OpenID Provider (OP) sets in the response.

    • consent: The authorization server prompts the end user for consent before giving information to the OAuth client. If the end user doesn’t consent, it returns an error.

    • select_account: The authorization server prompts the end user to specify which account they are using. If the end user doesn’t select an account, it returns an error.

    PingAccess configures the prompt parameter in the OIDC authentication requests that it generates. The token provider uses the value of the prompt parameter to confirm the end user’s presence or to emphasize the authentication request’s importance.

    You can set the Prompt Parameter on both the web session and on one of the OIDC authentication challenge response generators. A prompt parameter value set on a specific authentication challenge response generator takes precedence over one set on a web session. Learn more in Configuring authentication challenge policies.

    Select the Enable Push Authorization advanced setting if you’re using PingFederate as a token provider. This setting provides an extra layer of security against frontchannel tampering.

  • Select Enable Push Authorization to have PingAccess send a backchannel request at the token provider’s pushed authorization request (PAR) endpoint.

    PingAccess uses the token provider’s metadata value for the pushed_authorization_request_endpoint to determine where to send the request.

    This checkbox is cleared by default.

    Currently, PingAccess only supports PingFederate as the OP for PAR. PingAccess 7.2 and later use the OAuth 2.0 Pushed Authorization Requests (PAR) draft specification.

    PingFederate added support for this specification in version 10.2. Learn more in the PingFederate 10.2 release notes.

  • In the Validate Session section, click Yes to validate PingAccess sessions with a configured PingFederate instance during request processing.

    No is selected by default.

    If you enable this setting, PingAccess synchronizes with session logouts from PingFederate.

    To use this setting, you must perform additional configuration steps in PingFederate. Learn more in Server-side session management configuration.

    Changing this setting might affect existing ongoing sessions, forcing the user to reauthenticate to access protected resources.

    1. In the PingFederate Session State Cache field, enter a maximum amount of time, in seconds, before session synchronization takes effect.

      The default value is 60 seconds.

      This setting is only available if you enable the Validate Session setting.

  • In the Refresh User Attributes section, click Yes to have PingAccess periodically contact PingFederate to update user data that’s used in evaluating policy claims. Otherwise, click No.

    Yes is selected by default.

    User data refreshes occur when processing a request from the user’s session that has surpassed the Refresh User Attributes Interval. PingAccess caches the user attributes until the Refresh User Attributes Interval is surpassed again. This continues until the user session is terminated.

    This option works in conjunction with the PingAccess web session management features to automatically require user reauthentication if the user attribute data used as issuance criteria for a token in PingFederate causes the token to be revoked.

    PingFederate provides data according to its OIDC policy, which can pull data from the access token or from an attribute source lookup:

    • If it pulls data from the access token, the data doesn’t change until the token expires.

    • If it pulls data from an attribute source lookup, the new data is available whenever the query is made.

      If the PingFederate OIDC policy uses an attribute source lookup and has issuance criteria configured to only issue a token if the account is enabled, enabling Refresh User Attributes allows PingAccess to terminate the session the next time that the user accesses a protected resource if the user’s account was disabled in the user datastore.

      The Refresh User Attributes Interval determines the length of time that user data is cached, so a change that terminates a session can take up to 60 seconds (by default) to take effect.

      Changing this setting can affect existing ongoing sessions, forcing the user to reauthenticate to access protected resources.

      1. In the Refresh User Attributes Interval field, enter a maximum amount of time, in seconds, that PingAccess caches user data.

        The default value is 60 seconds.

        This setting is only available if you enable the Refresh User Attributes setting.

  • Select Cache User Attributes to have PingAccess cache user attributes internally for use in policy decisions:

    This checkbox is cleared by default.

    • If you enable this setting, an attribute list that’s longer than the maximum cookie size can contain information used to evaluate access requests. Maximum cookie size is typically 4096 bytes.

    • If you don’t enable this setting, user attribute data is encoded, signed, or encrypted, depending on the web session cookie type, then stored in the browser’s cookie store. The information is sent from the browser back to PingAccess with each request.

      Changing this setting can affect existing ongoing sessions, forcing the user to reauthenticate to access protected resources.

  • In the Request Preservation list, select a type of request data for PingAccess to preserve if the user is redirected to an authentication page when submitting information to a protected resource.

    Choose from:

    • None: PingAccess doesn’t preserve any request data.

    • POST (default): PingAccess preserves POST data only.

    • POST and Fragment: PingAccess preserves both POST and fragment data.

  • In the Web Storage list, select the type of web storage that PingAccess uses to temporarily preserve data about non-authenticated requests in the browser.

    Choose from:

    • Session Storage (default): PingAccess stores request preservation data for the current session. After the user authenticates successfully or closes the associated tab, PingAccess clears the data.

    • Local Storage: PingAccess stores request preservation data across multiple sessions on the same device. After the user authenticates successfully, PingAccess clears the data.

      If users commonly use Internet Explorer with security zones enabled and PingFederate is in a different zone than PingAccess, use Local Storage.

  • In the Timeout Groovy Script field, enter a Groovy script to customize web session durations for different types of users based on identity attributes that the token provider returns.

    Create a Timeout Groovy Script to overwrite a web session’s default <sessionTimeout> (representing the Max Timeout field) and <idleTimeout> (representing the Idle Timeout field) values. The following methods are unique to the Timeout Groovy Script:

    createTimeout()

    Creates an empty SessionTimeoutContext object.

    createTimeoutIdle(x)

    Creates an object with an <idleTimeout> of x minutes.

    createTimeoutSession(x)

    creates an object with a <sessionTimeout> of x minutes.

    createTimeout(x,y)

    Creates an object with a <idleTimeout> of x minutes and a <sessionTimeout>of y minutes.

    Enter specific user attributes in the script, such as client_id in the following example script:

    def context = createTimeout();
if (user.has("client_id"))
 {
   context = createTimeoutIdle(15);
 }
return context;

    When a user with one of the specified attributes opens a web session, PingAccess modifies the duration of the session according to the values that you set.

    When PingAccess issues a PingAccess token, it packages user attributes into a JsonNode object. Learn more about methods that might be useful, such as JsonNode get() or boolean has(), in the JsonNode object reference.

  • Select the Provide Authentication Feedback checkbox to configure PingAccess to let the authentication authority know why a user was redirected to it.

    This checkbox is cleared by default.

    Currently, PingAccess only provides this challenge reason feedback if the user’s web session times out.

    This option is available for the OIDC Authentication Request Redirect, Redirect Challenge, and Templated Challenge response generators. Learn more about the next steps in step 6d in the Configuring authentication challenge policies.

    PingAccess only sends a feedback key to the authentication authority. From there, the authentication authority must configure and display a user-facing message explaining why the redirect was necessary. In PingFederate, for example, the feedback key can be used within a velocity template. Velocity templates let you create custom user-facing messages, such as Your session has expired. Please log in again.

    On the web session admin API endpoint, Provide Authentication Feedback is expressed as provideAuthenticationFeedback.