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
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, or resource owners, before returning the validation results to
the clients. Depending on the features selected on the Session
Validation tab, PingFederate might return
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.
- Go to .
Select the applicable ATM instance or click Create New
If you are creating a new ATM instance, complete the required fields in the Type and Instance Configuration tabs.
On the Session Validation tab, select the check box for each
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.
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
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 .
- The authentication session has expired based on the Max Timeout field value in .
- 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
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 .
For externally stored authentication sessions, this operation only sends updates to the external storage when the remaining idle timeout window is less than 75%.