PingFederate Server

Managing session validation settings

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

Before you begin

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.

About this task

Edit the session validation settings on the Session Validation tab.

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.

Steps

  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.

    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.Access token management window, Session validation tab.

    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.

    When processing a refresh-grant token request through an ATM instance where this feature is enabled, PingFederate includes the same session identifier if the original access token includes one.

    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.

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