PingFederate Server

Session Revocation API endpoint

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. This endpoint is not part of the OAuth specification. You must select the Allow Access to Session Revocation API check box 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.

OAuth clients must authenticate to the web service using their configured client authentication method. For more information about OAuth client authentication methods, see Configuring OAuth clients.

If clients are allowed to add sessions to the revocation list, you can enable the Check session revocation status option in the applicable Access Token Management instances for the token validation process to consider whether a session has been added to the revocation list

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.

The POST method described in this section requires the element name/value pair formatted in JSON.

You can find information about the Session Revocation API endpoint in the OpenID Provider Configuration endpoint metadata: ping_revoked_sris_endpoint.
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.

Example

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

  • 200 – OK

    [.codeph]``\{"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

    [.codeph]``\{"resultId":"session_mgmt_sri_not_revoked","message":"The SRI has
                             not been revoked."}`` if the session is not found in the revocation list. If {pingfed} is configured to manage authentication sessions and the request does not come with the [.codeph]``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 through this endpoint in the runtime-api.log file. While the events themselves are not configurable, you can 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.