PingFederate Server

Session Management API by user identifiers

OAuth applications can send a user identifier to the Session Management API endpoint to query or revoke authentication sessions belonging to the end-user.

  • Allow Access to Session Management API must be enabled on an OAuth client to allow the client to access this session management API by user identifier.

  • Adapters must be configured with a Unique User Key Attribute, as described in Setting pseudonym and masking options.

  • The user_key specified in the session management API request must match the value of the Unique User Key Attribute determined at runtime.

  • This API is different than the other session management APIs in that it only returns currently valid sessions (status = HAS_VALID_SESSIONS). Revoked sessions (SESSION_REVOKED) or users without any sessions (NO_VALID_SESSIONS) will not be seen from this API.

  • The user_key parameter needs to be URL encoded (@ is encoded as %40) since the value appears as a query parameter in the URL.

Applications can query or revoke user sessions based on user identifiers. The bulk revocation capability provides a convenient way to expire server-side authentication sessions on a per-user basis if needed. When revoked and without valid credentials, such end-users will not be able to fulfill authentication requirements and access protected resources.

An OAuth client needs to obtain a user identifier and send it to the session management API in an HTTP GET or POST request. If the client is configured to obtain an access token, an ID token, or a User Info response, it could potentially get the user identifier that way. However, if the client is not configured to obtain one of these items, or if none of them delivers the applicable user identifier, the client can still use this endpoint by sending a user identifier. For example, an application for the help desk to query or revoke all authentication sessions for a given user falls into this category. In this example, the developer will build an application to prompt the help desk staff to provide a user identifier, which becomes the user_key parameter value, send a GET or POST request to the session management API endpoint, and display the result of the request.

The API returns information in JSON format about each session associated with the user, such as:

  • SRI

  • Status

  • Last activity time

  • Authentication sessions

    • Authentication Source

    • ID of the per-authentication source session information

    • Creation time

    • Idle and maximum timeout

  • Context data

    • IP address

    • User agent

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

An OAuth client can also send the user identifier to the session management API in an HTTP POST request to revoke the sessions.

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

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, allow the client to access the session management API, as described in Configuring OAuth clients

Session management API by user identifier endpoints

The session management API by user identifiers has one endpoint, which requires the user_key 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.

Endpoint /pf-ws/rest/sessionMgmt/users/{user_key}

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

Sample request
GET /pf-ws/rest/sessionMgmt/users/john%40test.com-east HTTP/1.1
Sample response
{
    "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"
        }
    ],
    "contextData": {
        "ipAddress": "127.0.0.1",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
    }
}

Endpoint /pf-ws/rest/sessionMgmt/users/{user_key}/revoke

Use HTTP POST requests to revoke all PingFederate runtime authentication sessions that are associated with the given user identifier user_key. After running this request, any revoked sessions will be logged with an event as "SRI_REVOKED" in the audit log.

Sample request
POST /pf-ws/rest/sessionMgmt/users/john%40test.com-east/revoke HTTP/1.1
Host: www.example.com
X-XSRF-Header: PingFederate
Authorization: Basic YWNfY2xpZW50OmdPWDh0NEQ...h3ZjI=
Cookie: PF=K60mOoBlTvWcD4frFzcKF5
Return codes

  • 200 OK: The request was successfully processed

  • 503 Service Unavailable: An error occurred while deleting stored sessions

You can optionally use the endpoints described in Session Management API by session identifiers if needed.