An OAuth client can take the pi.sri session identifier from its access token and send it to the session management API in an HTTP GET request. An OAuth client can also send the pi.sri to the session management API in an HTTP POST request to extend or revoke the sessions. The API returns information in JSON format about each session associated with the pi.sri, including:

  • Last activity time
  • Idle and maximum timeout time
  • Authentication source that created the session
Note:

The API response body includes only sessions that were configured with the authentication sessions capability described in Configuring authentication sessions.

The session management API works with sessions stored in persistent storage and across clustered nodes. For this API, the runtime APIs audit log only records session revoke events.

Important:

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

To configure PingFederate so that an OAuth client can use the session management API:

Session management API by session identifiers endpoints

The session management API by session identifiers has three endpoints, which all require the sri parameter.

The OpenID Provider configuration endpoint /.well-known/openid-configuration provides configuration information for OAuth clients to access the session management API endpoints. For more information, see OpenID Provider configuration endpoint.

The session management API endpoints return several response codes, including:

  • 200 OK: The request was successfully processed.
  • 400 Bad request: The format of the SRI is invalid.

Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}

Use HTTP GET requests to get information about all sessions associated with the pi.sri specified by the sri parameter.

Here is a sample GET request from a client to the /pf-ws/rest/sessionMgmt/sessions/{sri} endpoint:

GET /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA HTTP/1.1
Host: www.example.com
X-XSRF-Header: PingFederate
Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI=
Cookie: PF=K60mOoBlTvWcD4frFzcKF5

After receiving a successful request, the endpoint returns a response like one of the following samples, depending on whether the status is HAS_VALID_SESSIONS, NO_VALID_SESSIONS, or SESSION_REVOKED:

  • {
        "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
        "status": "HAS_VALID_SESSIONS",
        "lastActivityTime": "2020-06-10T17:25:00.461Z",
        "authnSessions": [  // This section can include multiple sessions
            {
                "authnSource": {
                    "sourceType": "IDP_CONN",
                    "id": "L07d8fse7dslShd6d_20HA8jP6",
                    "entityId": "Amazon_Africa_A"  // Only for IDP_CONN sourceType sessions
                },
                "id": "ba5a3d97afee5ef9450b710ff932680e3579dc7f",
                "creationTime": "2020-06-10T17:25:00.454Z",
                "idleTimeout": "2020-06-10T18:25:00.461Z",
                "maxTimeout": "2020-06-11T01:25:00.461Z"
            },
            {
                "authnSource": {
                    "sourceType": "ADAPTER",
                    "id": "HtmlFormAdapter",
                    "adapterType": "HTML Form IdP Adapter"  // Only for ADAPTER sourceType sessions
                },
                "id": "7cbef5022be8d841f14a95ace8987cbb34c77a21",
                "creationTime": "2020-06-10T17:25:00.454Z",
                "idleTimeout": "2020-06-10T18:25:00.461Z",
                "maxTimeout": "2020-06-11T01:25:00.461Z"
            }
        ]
    }
  • {
        "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
        "status": "NO_VALID_SESSIONS",
    }
    
  • {
        "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
        "status": "SESSION_REVOKED",
    }

Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}/extend

Use HTTP POST requests to extend the idleTimeout value of all sessions associated with the pi.sri specified by the sri parameter.

Here is a sample POST request from a client to the /pf-ws/rest/sessionMgmt/sessions/{sri}/extend endpoint:

POST /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA/extend HTTP/1.1
Host: www.example.com
X-XSRF-Header: PingFederate
Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI=
Cookie: PF=K60mOoBlTvWcD4frFzcKF5

After receiving a successful request, the endpoint returns a response like the following sample:

{
    "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
    "status": "HAS_VALID_SESSIONS",
    "lastActivityTime": "2020-06-10T18:15:00.461Z",  // Updated
    "authnSessions": [  // This section can include multiple sessions
        {
            "authnSource": {
                "sourceType": "IDP_CONN",
                "id": "L07d8fse7dslShd6d_20HA8jP6",
                "entityId": "Amazon_Africa_A"  // Only for IDP_CONN sourceType sessions
            },
            "id": "ba5a3d97afee5ef9450b710ff932680e3579dc7f",
            "creationTime": "2020-06-10T17:25:00.454Z",
            "idleTimeout": "2020-06-10T19:15:00.071Z",  // Extended
            "maxTimeout": "2020-06-11T01:25:00.461Z"
        },
        {
            "authnSource": {
                "sourceType": "ADAPTER",
                "id": "HtmlFormAdapter",
                "adapterType": "HTML Form IdP Adapter"  // Only for ADAPTER sourceType sessions
            },
            "id": "7cbef5022be8d841f14a95ace8987cbb34c77a21",
            "creationTime": "2020-06-10T17:25:00.454Z",
            "idleTimeout": "2020-06-10T19:15:00.071Z",  // Extended
            "maxTimeout": "2020-06-11T01:25:00.461Z"
        }
    ]
}

Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}/revoke

Use HTTP POST requests to revoke all sessions associated with the pi.sri specified by the sri parameter.

Here is a sample POST request from a client to the /pf-ws/rest/sessionMgmt/sessions/{sri}/revoke endpoint:

POST /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA/revoke HTTP/1.1
Host: www.example.com
X-XSRF-Header: PingFederate
Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI=
Cookie: PF=K60mOoBlTvWcD4frFzcKF5

After receiving a successful request, the endpoint returns a response like the following sample:

{
    "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
    "status": "SESSION_REVOKED",
}

Endpoint /pf-ws/rest/sessionMgmt/sessions/{sri}/authnSessions/{id}

Use HTTP DELETE requests to remove an authentication session with the specified id parameter from the sessions associated with the pi.sri specified by the sri parameter.

Here is a sample DELETE request from a client to the /pf-ws/rest/sessionMgmt/sessions/{sri}/authnSessions/{id} endpoint:

DELETE /pf-ws/rest/sessionMgmt/sessions/qzTEiEroxdzAufjYKQawm72lcBE..4RbA/authnSessions/ba5a3d97afee5ef9450b710ff932680e3579dc7f HTTP/1.1
Host: www.example.com
X-XSRF-Header: PingFederate
Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI=
Cookie: PF=K60mOoBlTvWcD4frFzcKF5

After receiving a successful request, the endpoint returns a response like the following sample:

{
    "sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA", 
    "status": "HAS_VALID_SESSIONS", 
    "lastActivityTime": "2020-06-10T18:15:00.461Z", // Not changed 
    "authnSessions": [ 
        // This section had an IdP connection authentication session 
        // with ID = "ba5a3d97afee5ef9450b710ff932680e3579dc7f" and is now removed. 
        // Only the adapter session remains. 
        { 
            "authnSource": { 
            "sourceType": "ADAPTER", 
            "id": "HtmlFormAdapter", 
            "adapterType": "HTML Form IdP Adapter" 
          }, 
          "id": "7cbef5022be8d841f14a95ace8987cbb34c77a21", 
          "creationTime": "2020-06-10T17:25:00.454Z", 
          "idleTimeout": "2020-06-10T19:15:00.071Z", 
          "maxTimeout": "2020-06-11T01:25:00.461Z" 
        } 
    ]
}