If you are using PingFederate as the OpenID Connect (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.
    1. In PingAccess, go to Access > Web Sessions, click the Expand icon to view more details about the web session associated with your API application, then click the Pencil icon.
  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 could affect existing ongoing sessions, forcing the user to reauthenticate 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 reauthenticate to access protected resources.

  6. In the OpenID Connect Login Type field, specify the 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 (RP) 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.
    Note:

    The OAuth client that 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 reestablishment 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. When the PingAccess Token expires, an authenticated user must reauthenticate. This protects against unauthorized use of a resource, ensuring that a session ends after the specified time and requiring the user to reauthenticate 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 Setting Description

    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 redirecting the user to reauthenticate 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

    In 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 does 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 PingAccess 7.0 Release Notes 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.

    Prompt Parameter

    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:

    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. The authorization server doesn't prompt the end-user with a consent or authentication page if this option is selected.
    login
    The authorization server prompts the end-user to reauthenticate. If the end-user doesn't reauthenticate successfully, it returns an error.
    Note:

    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 give their consent, it returns an error.
    select_account
    The authorization server prompts the end-user to specify which account they are using, in case they have multiple accounts. If the end-user doesn't select an account, it returns an error.

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

    Important:

    You can set the Prompt Parameter in two places: on the web session, or 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. For more information, see Configuring authentication challenge policies.

    Regardless of where you configure the prompt parameter value, you should select Enable Push Authorization, the advanced setting described below, if you are using PingFederate as a token provider. This setting provides an extra layer of security against frontchannel tampering.

    Enable Push Authorization

    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.

    Important:

    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, so make sure that you are using PingFederate 10.2 or later. For more information, see the PingFederate 10.2 release notes.

    Validate Session

    Select Validate Session to validate PingAccess sessions with the configured PingFederate instance during request processing. This option is not selected by default.

    If you enable this setting, PingAccess synchronizes with session logouts from PingFederate. The PingFederate Session State Cache setting defines the maximum delay before session synchronization takes effect.

    Important:

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

    Note:

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

    Refresh User Attributes

    When you enable Refresh User Attributes, PingAccess periodically contacts 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 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 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 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.

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

    Timeout Groovy Script

    Create a Timeout Groovy Script to customize web session durations for different types of users based on their attributes. These identity attributes are returned by the token provider. Specifically, a Timeout Groovy Script is used to overwrite a web session's default <sessionTimeout> (representing the Max Timeout field) and <idleTimeout> (representing the Idle Timeout field) values. The following parameters 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, like client_id from the following script example:

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

    Whenever a user with one of the specified attributes opens a web session, the duration of the session is modified according to values you set with the script-specific constructors.

    Note:

    User attributes are packaged into a JsonNode object when a PingAccess token is issued. See JsonNode object reference for a list of methods which might be useful, like JsonNode get() and boolean has().

    Provide Authentication Feedback

    Select the Provide Authentication Feedback check box to configure PingAccess to let the authentication authority know why a user was redirected to it. Currently, PingAccess only provides this challenge reason feedback if the user's web session has timed out.

    This option is available for the OIDC Authentication Request Redirect, Redirect Challenge, and Templated Challenge response generators. For more information and next steps, see step 6d on the Configuring authentication challenge policies page.

    Important:

    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.

    Tip:

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

  12. Click Save.