PingFederate includes a REST-based web service for back-channel session revocation. This service enables OAuth clients to add sessions to the revocation list or to query their revocation status. Note that this endpoint is not part of the OAuth specification. The Grant Access to Session Revocation API check box must also be selected in the configuration for the applicable clients. This endpoint is a URL path extension of the PingFederate runtime endpoint; for example:

https://www.example.com:9031/pf-ws/rest/sessionMgmt/revokedSris

Important:

OAuth clients must authenticate to the web service using their configured client authentication method.

Note:

Generally speaking, if clients are allowed to add sessions to the revocation list, consider enabling the Check session revocation status option in the applicable Access Token Management instances so that the token validation process takes into account whether a session has been added to the revocation list. (For more information, see Managing session validation settings.)

Endpoint: /pf-ws/rest/sessionMgmt/revokedSris

This resource accepts the POST and GET methods. It also requires the X-XSRF-HEADER HTTP header with any value to prevent cross site request forgery.

Note:

The POST method described in this section requires the element name/value pair formatted in JavaScript Object Notation (JSON).

Tip:

Information about the Session Revocation API endpoint is also available in the OpenID Provider Configuration endpoint. Look for ping_revoked_sris_endpoint in the metadata.

POST
A POST request adds a session to the revocation list based on its session identifier (id) in the POST data. The ID value corresponds to that of the pi.sri element in the ID token. The required Content-Type is application/json.
Sample request
A POST request to add a session with a session identifier of abc123 to the revocation list:
POST /pf-ws/rest/sessionMgmt/revokedSris
Host: localhost:9031
Authorization: Basic YWNfb2ljX2NsaWVudDphYmMxMjNERUZnaGlqa2xtbm9wNDU2N3JzdHV2d3h5elpZWFdVVDg5MTBTUlFQT25tbGlqaG9hdXRocGxheWdyb3VuZGFwcGxpY2F0aW9u
X-XSRF-HEADER: PingFederate
Content-Type: application/json

{"id":"abc123"}
Return codes
  • 201 – Created

    The session is added to the revocation list.

  • 400 – Bad Request

    The X-XSRF-HEADER HTTP header is not found in the HTTP POST request.

  • 401 – Unauthorized

    The response contains details as to why the attempt failed.

  • 415 – Unsupported Media Type

    The Content-Type: application/json HTTP header is not found in the HTTP POST request.

  • 500 – Internal Server Error

    An unknown error has occurred.

GET
A GET request sends a query for the revocation status for a session with its session identifier (id) appended to the endpoint. The ID value corresponds to that of pi.sri in the ID token.
Sample request
A GET request to query the revocation status for a session with a session identifier of abc123:
GET /pf-ws/rest/sessionMgmt/revokedSris/abc123
Host: localhost:9031
Authorization: Basic YWNfb2ljX2NsaWVudDphYmMxMjNERUZnaGlqa2xtbm9wNDU2N3JzdHV2d3h5elpZWFdVVDg5MTBTUlFQT25tbGlqaG9hdXRocGxheWdyb3VuZGFwcGxpY2F0aW9u
X-XSRF-HEADER: PingFederate

If PingFederate authentication sessions are enabled, querying a valid session also extends the session lifetime by the time value specified in the global Idle Timeout field or the idle timeout override for the authentication source associated with the session. The latter takes precedence. 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%.

Alternatively, include the optional updateActivityTime query parameter and set the value to false in the request to query the status of a session without extending its lifetime; for example:

GET /pf-ws/rest/sessionMgmt/revokedSris/abc123&updateActivityTime=false
Host: localhost:9031
Authorization: Basic YWNfb2ljX2NsaWVudDphYmMxMjNERUZnaGlqa2xtbm9wNDU2N3JzdHV2d3h5elpZWFdVVDg5MTBTUlFQT25tbGlqaG9hdXRocGxheWdyb3VuZGFwcGxpY2F0aW9u
X-XSRF-HEADER: PingFederate
Return codes
  • 200 – OK

    {"id":"abc123"} is found in the revocation list.

  • 400 – Bad Request

    The X-XSRF-HEADER HTTP header is not found in the HTTP POST request.

  • 401 – Unauthorized

    The response contains details as to why the attempt failed.

  • 404 – Not Found

    {"resultId":"session_mgmt_sri_not_revoked","message":"The SRI has not been revoked."} if the session is not found in the revocation list. As previously stated, if PingFederate has been configured to manage authentication sessions and the request does not come with the updateActivityTime=false query parameter, the session is extended as well.

  • 500 – Internal Server Error

    An unknown error has occurred.

Logging

PingFederate records the actions performed via this endpoint in the runtime-api.log file. While the events themselves are not configurable, you may adjust the log4j2.xml configuration settings to alter the format and desired level of detail surrounding each event.

Each log entry contains information relating to the event, including:

  • Time the event occurred on the PingFederate server
  • Administrator username performing the action
  • Authentication method
  • Client IP
  • HTTP method
  • REST endpoint
  • HTTP status code

Each of the above fields is separated by a vertical pipe (|) for ease of parsing.