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.

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

When any session validation features are 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 JSON web token (JWT)-based access tokens, the session identifier is part of the access token. Through the session identifier, an OAuth client can contact the Session Management API and Session Revocation API endpoints to query the status of an authentication session, or to extend or revoke an authentication session.

The session validation features let you combine the status of access tokens and user authentication sessions. Because you can independently enable each feature per access token management (ATM) instance, you can customize unique API and web single sign-on (SSO) behaviors for your OAuth clients and users.
Important:

The session validation features are most suitable for clients using the implicit grant type, which does not use refresh tokens. Clients using the authorization code grant type can still use session validation. However, they can only refresh their access tokens through ATM instances that have the session validation features disabled, other than the Include session identifier in access token feature.

When a client using the authorization grant type has an access token and sends a refresh token to an ATM instance, the following rules apply:

  • If the ATM instance has Include session identifier in access token enabled and the other session validation features disabled, then the ATM instance can issue a new access token. If the original access token contains a session identifier, the new token will contain the same session identifier.
  • If the ATM instance has any session validation feature enabled other than the Include session identifier in access token feature, then PingFederate returns an unsupported_grant_type error.
  • If the ATM instance has Include session identifier in access token disabled and the other session validation features disabled, then the ATM instance can issue a new access token, but with no session identifier.
  1. Go to Applications > OAuth > Access Token Management.
  2. Select the applicable ATM instance or click Create New Instance.

    If you are creating a new ATM instance, complete the required fields in the Type and Instance Configuration tabs.

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

    If authentication sessions are not enabled, you can still select features on this tab, but access token validation might fail.

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

    Each feature is independent of each other. The following table describes each feature.

    Feature Description
    Include session identifier in access token When selected, the ATM instance includes the value of the pi.sri session identifier in the access tokens it issues. An OAuth client that is allowed to access the session management API can get information about sessions associated with the session identifier. The client can also request PingFederate to extend or revoke the sessions. For more information, see Session Management API by session identifiers.
    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 in Authentication > Policies > Sessions.
    • The authentication session has expired based on the Max Timeout field value in Authentication > Policies > Sessions.
    • The authentication session is not found, such as if the user has logged out.

    You can also optimize the access token lifetime.

    Note:

    If this ATM instance issues internally managed reference tokens, match the Token Lifetime value in the Instance Configuration tab to the Idle Timeout value. If you specify a Maximum Token Lifetime value on the Instance Configuration tab, 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 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 through 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 in Authentication > Policies > Sessions.

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