When an OAuth client presents an access token for validation, PingFederate (as an OAuth authorization server) checks the expiration and the other aspects of the access token. If the validation fails, PingFederate returns an invalid_grant error to the client.

When PingFederate authentication sessions are enabled, you can optionally configure the access token validation process to evaluate the authentication sessions of the users (the resource owners) before returning the validation results to the clients. Depending on the feature (or features) selected on the Session Validation screen, PingFederate may return to the client an invalid_grant error if the associated authentication session has timed out (or expired), is not found, or has been revoked. Moreover, you may also configure PingFederate to extend the authentication sessions upon successful validations.

When any of the session validation features is enabled, the associated session identifier (pi.sri) becomes available through the access tokens. For reference-style access tokens, PingFederate returns the associated session identifier in the response if the access token is valid. For JWT-based access tokens, the session identifier is part of the access token. With the session identifier, an OAuth client may contact the Session Revocation API endpoint to query the status of an authentication session or to revoke an authentication session.

In essence, the session validation features enable you to conjoin the validity of access tokens and the authentication sessions of the users. Because each feature can be independently enabled or disabled per access token management (ATM) instance, you can fully customize unique API and web SSO experiences for your OAuth clients and thus the users.

Important:

Once any of the session validation features is enabled for an ATM instance, clients will not be able to obtain an access token through that ATM instance by presenting a refresh token. Any attempt will result in an unsupported_grant_type error. The reason being is that such action, if allowed, defeats the purpose of tying the validity of access tokens and the authentication sessions of the users in the first place. Hence, it follows that the Session Validation features are most suitable for clients using the Implicit grant type because they do not use refresh tokens. That said, clients using the Authorization Code grant type can still take advantage of session validation as needed; they just will not be able to use refresh tokens to obtain access tokens through the ATM instances that have the session validation features enabled.

  1. Go to the OAuth Server > Access Token Management screen.
  2. Select the applicable ATM instance or click Create New Instance to create a new ATM instance.

    If you are creating a new ATM instance, provide the required information on the Type and Instance Configuration screens.

  3. On the Session Validation screen, select the check box for each relevant feature.
    Important:

    The session validation features require authentication sessions. You must enable authentication sessions for either all authentication sources or the authentication source associated with the OAuth use cases.

    If authentication sessions are not enabled, you may still continue selecting features on this screen; however, access token validation may fail until authentication sessions are enabled.

    If this is a child instance, select the Override Session Validation Settings check box and make the adjustments as needed.

    Refer to the following table for information about each feature. Each feature is independent of each other.

    Feature Description
    Check for valid authentication session When selected, an access token is considered invalid unless the user has a valid authentication session. If the user does not have a valid session, PingFederate returns an invalid_grant error.

    An authentication session is invalid when one of the following conditions applies:

    • The authentication session has timed out based on the Idle Timeout field value on the Sessions screen.
    • The authentication session has expired based on the Max Timeout field value on the Sessions screen.
    • The authentication session is not found; for example, the user has logged out.

    You may also optimize the access token lifetime.

    • If this ATM instance issues internally managed reference tokens, match the value of the Token Lifetime (on the previous screen, Instance Configuration) to that of the Idle Timeout. Similarly, if you choose to specify a Maximum Token Lifetime value on the Instance Configuration screen, ensure that the value matches that of the Max Timeout field.
    • If this ATM instance issues JWT-based access tokens, match value of the Token Lifetime field to that of the Max Timeout field.
    Check session revocation status When selected, PingFederate verifies whether the session identifier (pi.sri) has been added to the revocation list. If the session has been revoked, PingFederate returns an invalid_grant error.

    An authentication session can be revoked via the front-channel or the back-channel.

    Update authentication session activity When selected, if the access token is valid, PingFederate also extends the lifetime of the authentication session by the Idle Timeout field value on the Sessions screen.

    For externally stored authentication sessions, this operation is optimized to only send updates to the external storage when the remaining idle timeout window is less than 75%.