[Design Discussion] Session visibility - list live SSO sessions per user and per application

[rasandilikshana]

Related Feature Issue

#3400

Problem Summary

ThunderID persists SSO sessions (flow-centric browser SSO) but gives administrators and
end users no way to see them. Without a read path, operators cannot answer basic security
questions such as "where is this user signed in" or "who has live sessions on this
application". Session visibility is the foundation of the session management epic (#3394);
this design covers the read path proposed in #3400.

High-Level Approach

• Add a read-only session management API: GET /sessions?userId= and GET /sessions?appId=
  for administrators, and GET /sessions/me for the authenticated caller.
• Record sessions for all applications, not only the Console: add the SSO check and
  session checkpoint nodes to the Default Authentication Flow in the bootstrap resources.
• Gate the admin endpoints with a new system:session:view permission.
• Resolve display names (user name, application name) server-side and embed them in the
  response, so clients need no extra list permissions and no follow-up requests.
• Surface the data in the Console: a Sessions tab on the user edit page (sessions with
  participating applications) and on the application edit page (sessions with the user).

Architecture Overview

Components:

• backend/internal/flow/session/mgt: new management subpackage (handler, models, errors)
  following the flow/mgt and design/theme/mgt conventions. It calls a ManagementService in
  the session package backed by read-only queries over the existing SSO_SESSION and
  SSO_SESSION_PARTICIPANT tables in the operation database.
• Queries filter to live sessions only (ACTIVE state, idle and absolute expiry checked
  against a caller-supplied reference time) with server-side pagination (limit clamped to
  the server maximum, offset, totalResults and links). One new index
  (APP_ID, DEPLOYMENT_ID) is added to both the PostgreSQL and SQLite scripts to support
  the per-application listing.
• A name resolver wired in servicemanager maps subject IDs to user display names and
  application IDs to application names at response-build time, deduplicated per page.
• Frontend: new @thunderid/configure-sessions workspace package (TanStack Query hook with
  server-driven pagination, DataGrid-based SessionsTable) consumed by the Console
  application edit page and the configure-users user edit page.
• Bootstrap: the Default Authentication Flow gains sso_check and session_checkpoint nodes;
  flow definitions are versioned, so existing deployments pick the change up as a new
  flow version on the next bootstrap.

Security Considerations

• Admin listing endpoints require the new system:session:view permission. GET /sessions/me
  derives the subject from the authenticated token and returns only the caller's sessions.
• Responses expose session metadata only (identifiers, timestamps, participants, resolved
  display names). The session handle used as the browser credential is never serialized.
• The limit parameter is clamped to the server maximum page size to prevent unbounded
  result sets.
• Display-name resolution happens server-side under the server's own privileges, so a
  viewer does not need user-list or application-list permissions, and no additional data
  beyond names is disclosed.
• The API is strictly read-only; no session mutation is introduced in this slice.

Impacted Areas

• Flow engine bootstrap definitions (Default and Console authentication flows)
• Session subsystem (backend/internal/flow/session): new read-only management paths
• Security permission registry (system:session:view)
• Operation database (new index; read queries only, no schema changes to existing tables)
• Console UI: application edit page, user edit page, new configure-sessions package
• No changes to OAuth2/OIDC protocol surfaces

Alternatives Considered

Alternative 1: Resolve user and application names client-side in the Console by
fetching the user and application lists.

• Pros: no backend changes for name display.
• Cons: downloads entire directories to label one page, breaks beyond the server's
  default page size, and requires viewers to hold extra list permissions.
• Decision: resolve names server-side and embed them in the response.

Alternative 2: Keep session recording Console-only (status quo) and ship the UI as is.

• Cons: the Sessions tabs would stay empty for every application on the default flow,
  which reads as a broken feature.
• Decision: extend the Default Authentication Flow so all default-flow applications
  record sessions.

Alternative 3: Expose management reads from the runtime session store interface.

• Cons: couples the hot login/SSO path to admin API churn.
• Decision: a dedicated mgt subpackage with its own read paths, matching how flow and
  theme management are structured.

Questions for Community Input

1. Should a Session resource with a view action be added to the bootstrap resource-server
   catalog so system:session:view becomes assignable to scoped roles? Today only the
   blanket system permission covers it, matching the existing agenttype pattern.
2. Session termination (revoking a session from these views) is the natural next slice.
   Preference on scope: administrator revocation first, or self-service alongside?
3. SessionExecutor currently fails the whole flow if a session resolved by sso_check
   disappears before the checkpoint load (pre-existing behavior, see SessionExecutor fails the whole flow when a resolved session vanishes before checkpoint load #4137). Should
   graceful fallback to the credential prompt live in the executor or the engine?
4. Should registration and recovery flows also record sessions in this slice, or as a
   follow-up?

[madurangasiriwardena]

Thanks for writing this up, I want to highlight 2 main concerns in the proposal.

1. The listing payload cannot identify a session

The stated response shape is "identifiers, timestamps, participants, resolved display names". That is everything except what a human uses to recognise a session. Asked "is this you?", nobody can answer from a session id and a pair of timestamps. A "your devices / active sessions" view needs the what and the where, and none of it is stored today: SSO_SESSION captures identity, lifecycle, and timestamps only. Nothing threads request metadata to the session layer today.

The split that matters is between what has to be captured when the session is established and what can be worked out at render time.

Must be captured at establishment, because it is request-time only and unrecoverable afterwards:

• Device / User-Agent, browser and OS, stored as plaintext for display.
• Creation IP and last-active IP, honouring X-Forwarded-For and trusted-proxy configuration.

Derivable at display time, so should not be stored:

• Application name, from SSO_SESSION_PARTICIPANT.APP_ID.
• Location, city and country, can be geo-resolved from the stored IP when rendering.

2. What is the session identifier in the response?

"Identifiers" in the response shape needs pinning down. The design is right that the handle is never serialized: it is the browser credential, and putting it in a response body, a URL, or a DOM attribute would hand out the thing that is the session. That has to hold.

But the rows still need a stable identity that is safe to expose. SESSION_ID is the natural candidate.

[rasandilikshana]

Thank you for the feedback @madurangasiriwardena, both points make sense. I will update
the proposal so device/User-Agent and IP addresses (creation and last-active) are
captured at session establishment, with application names and geo-location resolved at
display time, and SESSION_ID as the stable identifier exposed in responses. I will
revise the design here before updating the implementation.