If you are using PingFederate as the OIDC token provider and plan to use Mutual TLS, you must make two changes to the PingFederate configuration.

  • Enable the use of the secondary HTTPS port in PingFederate by editing the <PF_HOME>/pingfederate/bin/run.properties file and setting the pf.secondary.https.port value to a port value. For more information, see the PingFederate documentation.
  • Modify the openid-configuration.template.json to add the mtls_endpoint_aliases object, with content defined by RFC-8705. For more information about this file, see the PingFederate documentation.
  1. Click Access and then go to Web Sessions > Web Sessions.
  2. Click + Add Web Session.
  3. In the Name field, enter a unique name for the web session, up to 64 characters, including special characters and spaces.
  4. Select a Cookie Type.

    An encrypted JSON web token (JWT) uses authenticated encryption to simultaneously provide confidentiality, integrity, and authenticity of the PingAccess token. Encrypted JWT is the default setting.

    A Signed JWT uses asymmetric cryptography with a private/public key pairing to verify the signed message and to confirm that the message was not modified during transit.

    Changing this setting may affect existing ongoing sessions, forcing the user to re-authenticate to access protected resources.

  5. In the Audience field, specify the audience that the PingAccess token is applicable to, represented as a short, unique identifier between 1 - 32 characters.

    Requests are rejected that contain a PingAccess token with an audience that differs from what is configured in the web session associated with the target application. Changing this setting can affect existing ongoing sessions, forcing the user to re-authenticate to access protected resources.

  6. In the OpenID Connect Login Type field, specify the OpenID Connect (OIDC) login type.

    For more information on the available profiles, see OpenID Connect login types.

  7. In the Client ID field, select the client ID that was assigned when you created the OAuth relying party client within PingFederate.

    For more information, see Configuring a Client. Enter the unique identifier (Client ID).

  8. Select a Client Credentials Type, then provide the information required for the selected credential type.

    This is required when configuring the Code login type.

    • Secret – Enter the Client Secret assigned when you created the OAuth relying party client in the token provider.
    • Mutual TLS – Select a configured Key Pair to use for Mutual TLS client authentication.
    • Private Key JWT – Select this option to use Private Key JWT. No additional information is required.

    The OAuth client you use with PingAccess web sessions must have an OIDC policy specified. For more information, see Configuring OpenID Connect Policies.

  9. In the Idle Timeout field, specify an idle timeout that defines the amount of time, in minutes, that the PingAccess token remains active when no activity is detected by the user.

    The default is 60 minutes.

    If there is an existing valid PingFederate session for the user, an idle timeout of the PingAccess session might result in its re-establishment without forcing the user to sign on again

  10. In the Max Timeout field, specify a max timeout that defines the maximum amount of time, in minutes, that the PingAccess token remains active.

    The default is 240 minutes. Once the PingAccess Token expires, an authenticated user must re-authenticate. This protects against unauthorized use of a resource, ensuring that a session ends after the specified time and requiring the user to re-authenticate to continue.

    Note:

    This value needs to be smaller than the PingFederate access token lifetime defined in the PingFederate access token management instance. For more information, see Configuring Reference-Token Management.

  11. Optional: To configure advanced settings, click Show Advanced.
    Advanced settingDescription
    Cookie Domain
    Specify the valid Cookie Domain where the cookie is stored, such as corp.yourcompany.com.
    Note:

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

    Secure Cookie

    Select Secure Cookie to indicate that the PingAccess cookie must be sent using only HTTPS connections. This is selected by default.

    Note:

    Setting an invalid Cookie Domain or selecting Secure Cookie in a non-HTTPS environment causes authentication to fail. This results in PingAccess re-directing the user to re-authenticate with PingFederate indefinitely.

    HTTP-Only Cookie Select HTTP-Only Cookie to enable the HttpOnly flag on cookies that contain the PingAccess token. An HttpOnly flagged cookie is not accessible using non-HTTP methods such as calls through JavaScript, like referencing document.cookie, and cannot be easily stolen using cross-site scripting.
    Enable PKCE If you want PingAccess to send a SHA256 code challenge and corresponding code verifier as a proof key for code exchange during the code authentication flow, click Enable PKCE.
    SameSite Cookie

    From the SameSite Cookie list, select the level of restriction for when cookies can be sent in a cross-site request. The options are:

    • Lax – The cookie should be sent on the initial navigation to a site, and is sent in same-site requests but not cross-site requests.
    • None – The cookie is intended to be used across different sites without restriction.
    • Disabled – The SameSite attribute is not set. This option is the default.
    Note:

    Safari 12 will not function correctly if the SameSite attribute is set to None. Regardless of the selected setting, the SameSite attribute is disabled if Safari 12 is detected.

    Note:

    See the Known Issues and Limitations for information about a browser issue that can prevent sign on if the SameSite Cookie attribute is set.

    Scopes

    Configure the Scopes you want to request from the token provider when requesting the ID token. If you have a token provider configured, published scopes are available to select from the list based on the selected Client ID. You can specify unverified scopes by typing the scope and clicking Use unverified scope "[scopename]".

    Your token provider must be properly configured to handle all of the requested scopes you specify, including any custom scope values.

    Note:

    The user can access all attributes by examining browser traces. While they are integrity protected to prevent changes, any sensitive or confidential attributes can be viewed should the user decode the ID Token's value.

    Validate Session

    Select Validate Session so that PingAccess will validate sessions with the configured PingFederate instance during request processing. Use of this feature requires additional configuration in PingFederate. This option is not selected by default.

    Session timeouts are synchronized between PingAccess and PingFederate when the following conditions are met:

    • A minimum release of PingFederate 8.2 is deployed with Authentication Session Settings configured.
    • You have selected the Validate Session check box.

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

    Refresh User Attributes

    When you enable Refresh User Attributes, PingAccess will periodically contact PingFederate to update user data used in evaluating policy claims. This option works in conjunction with the PingAccess web session management features to automatically require user re-authentication if 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 does not 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 this web session option allows PingAccess to terminate the session the next time 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 the user data is cached, so the effect of a change that results in a session being terminated may take up to 60 seconds (by default) to take effect.

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

    This option is selected by default.

    Cache User Attributes

    When Cache User Attributes is enabled, PingAccess caches user attributes internally for use in policy decisions. By doing this, an attribute list that is longer than the maximum cookie size can contain information used to evaluate access requests. In practice, this is 4096 bytes, although the maximum cookie size can vary depending on the browser.

    When this option is disabled, user attribute data is encoded, signed or encrypted, depending on the web session cookie type, and 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 re-authenticate to access protected resources.

    This option is not selected by default.

    Consult Server Duration
    Specify a Consult Server Duration to define the maximum amount of time, in seconds, that a PingAccess agent caches policy decisions for the web session before sending a request to the policy server. This option only applies to agents.
    Note:

    The value used for this setting should not be larger than the idle timeout value, and ideally should be defined to be a value less than half the timeout.

    Request Preservation

    Select Request Preservation to specify the type of request data to be preserved if the user is redirected to an authentication page when submitting information to a protected resource. Available options are None, POST, or POST and Fragment.

    Web Storage

    Specify the type of Web Storage for request preservation data.

    Use Session Storage, and use Local Storage if it is common for users to use Internet Explorer with security zones enabled and PingFederate is in a different zone than PingAccess.

  12. Click Save.