The runtime session management API lets OAuth clients get information about user sessions, extend sessions, and revoke sessions. Knowing the remaining lifetime of a valid session could, for example, let an application prompt the user to extend the session.
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. Then the API returns information in JSON format about each session associated with the pi.sri, such as:
- Last activity time
- Idle and maximum timeout time
- Authentication source that created the session
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.
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
- Configure the client's access token manager instance to include a pi.sri in access tokens, as described in Managing session validation settings
Session management API endpoints
The session management API 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.
Sample request:
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
Sample response 1:
{
"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
},
"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
},
"creationTime": "2020-06-10T17:25:00.454Z",
"idleTimeout": "2020-06-10T18:25:00.461Z",
"maxTimeout": "2020-06-11T01:25:00.461Z"
}
]
}
Sample response 2:
{
"sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
"status": "NO_VALID_SESSIONS",
}
Sample response 3:
{
"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.
Sample request:
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
Sample response:
{
"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
},
"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
},
"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.
Sample request:
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
Sample response:
{
"sri": "qzTEiEroxdzAufjYKQawm72lcBE..4RbA",
"status": "SESSION_REVOKED",
}