Session Management

When using server-side sessions, there is a record of the user’s authentication activity at IdentityServer. This allows administrative and management tooling to be built on top of that data to query those sessions, and terminate them. In addition, since the session data has its own unique id and tracks clients that a user has used, then some types of tokens issued to these clients can be revoked. Finally, if clients support back-channel logout, then they can be notified that a user’s session has been terminated, which allows them to also terminate the user’s session within the client application.

These features are all provided via the ISessionManagementService service.

ISessionManagementService

The session management service provides administrative operations for querying and revoking the server-side sessions.

Quickstart UI

The Quickstart UI contains a simple administrative page (under the “ServerSideSessions” folder) that uses the ISessionManagementService API.

Note

The Quickstart session administrative page requires a logged-in user to manage sessions. We strongly recommend that you add additional authorization suitable to your organization by adding an authorization policy.

The session management page looks like this by default, but of course you are free to customize or change it as needed:

Querying Sessions

Use the QuerySessionsAsync API to access a paged list of user sessions. You can optionally filter on a user’s claims mentioned above (subject identifier, session identifier, and/or display name).

For example:

var userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
{
    CountRequested = 10,
    SubjectId = "12345",
    DisplayName = "Bob",
}, HttpContext.RequestAborted);

The results returned contains the matching users’ session data, and paging information (depending on if the store and backing database supports certain features such as total count and current page number).

This paging information contains a ResultsToken and allows subsequent requests for next or previous pages (set RequestPriorResults to true for the previous page, otherwise the next page is assumed):

// this requests the first page
var userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
{
    CountRequested = 10,
}, HttpContext.RequestAborted);

// this requests the next page relative to the previous results
userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
{
    ResultsToken = userSessions.ResultsToken,
    CountRequested = 10,
}, HttpContext.RequestAborted);

// this requests the prior page relative to the previous results
userSessions = await _sessionManagementService.QuerySessionsAsync(new SessionQuery
{
    ResultsToken = userSessions.ResultsToken,
    RequestPriorResults = true,
    CountRequested = 10,
}, HttpContext.RequestAborted);

Terminating Sessions

To terminate session(s) for a user, use the RemoveSessionsAsync API. This accepts a RemoveSessionsContext which can filter on the subject and/or the session identifier to terminate. It then also has flags for what to terminate or revoke. This allows deleting a user’s session record in the store, any associated tokens or consents in the operational database, and/or notifying any clients via back-channel logout that the user’s session has ended. There is also a list of client identifiers to control which clients are affected.

An example to revoke everything for current sessions for subject id 12345 might be:

await _sessionManagementService.RemoveSessionsAsync(new RemoveSessionsContext {
    SubjectId = "12345"
}, HttpContext.RequestAborted);

Or to just revoke all refresh tokens for current sessions for subject id 12345 might be:

await _sessionManagementService.RemoveSessionsAsync(new RemoveSessionsContext {
    SubjectId = "12345",
    RevokeTokens = true,
    RemoveServerSideSession = false,
    RevokeConsents = false,
    SendBackchannelLogoutNotification = false,
}, HttpContext.RequestAborted);

Internally this uses the IServerSideTicketStore, IPersistedGrantStore and IBackChannelLogoutService features from IdentityServer.

Orphaned Grant Revocation on Session Overwrite

When a session cookie key is reused by a different user or a new session (that is, the subject ID or session ID stored in the cookie no longer matches what is in the server-side store), IdentityServer automatically revokes the grants that belonged to the previous session before writing the new one. The grants revoked are:

• refresh tokens
• reference tokens
• authorization codes
• backchannel authentication requests

This prevents tokens from a previous user’s session from remaining valid after the session is overwritten. Without this cleanup, a user whose session was silently replaced could retain working tokens even though their session no longer exists in the store.