Basic SSO: reuse an existing login session across applications

[madurangasiriwardena]

What problem are we solving?

Thunder authenticates every application independently — there is no reusable login session, so a user who already authenticated in the browser must re-authenticate for each application and each attempt. Basic SSO means reusing a live session for a later application: skipping the steps already satisfied, while still enforcing whatever the flow mandates.

This needs three problems solved:

1. Knowing whether a session exists. Given an incoming request, how do we tell that the caller already has a live login session, in a way that is not tied to a single transport and that we can trust the session is genuinely theirs?
2. Deciding what may be skipped. When a session does exist, which applications are even allowed to reuse it (what is the SSO boundary?), and within an authentication flow, which steps are already satisfied and may be skipped versus which must still run? Re-running everything defeats SSO; skipping the wrong step weakens security.
3. Continuing the flow correctly afterward. Once steps are skipped, the flow still needs the subject and the facts those steps would have produced in order to continue and complete. What must be carried in the session so a later authentication can resume from it, and which flows should be session-managed at all?

Scope: basic browser SSO only.

[madurangasiriwardena]

Detailed design

SSO is expressed as a property of the authentication flow graph — the flow author decides what an existing session lets them skip — rather than as central requirement-matching. Mapping to the three problems in the issue:

1. Knowing whether a session exists — the session is referenced by an opaque handle decoupled from its transport (a cookie carries it for browsers). A resolver loads the session and returns it only if it is live and correctly bound to the caller.
2. Deciding what may be skipped — the SSO boundary is a flow: a session belongs to exactly one flow, so only applications configured with the same flow can SSO. A Check SSO Session node detects a live same-flow session and routes past the already-satisfied steps to a join; steps placed after the join still run on every execution.
3. Continuing the flow correctly — a Save / Load Session node at the join persists the established flow status into the session (fresh auth) or loads it (reuse), so execution continues with the authenticated subject and facts. Whether a flow contains this node is what makes that flow session-managed.
   Trade-off, stated up front: SSO works only across identical flows. Two apps whose flows merely overlap (e.g. u+p vs u+p+MFA) will not SSO — they are different groups. This is simpler and explicit, at the cost of cross-flow "reuse the overlap, step up the gap" behaviour.

---

Flow

An authentication flow shared by several apps. Credential collection is skipped on SSO; the steps after the join (**Authorization**, then assertion generation) run every time.

• START.
• Check SSO Session ("is the user logged in with the flow?") — resolves the incoming handle to a session for this flow. Present (green) routes straight to Save / Load Session, skipping credentials; absent (red) drops into the Sign In path.
• View → Identifier + Password (absent path only) — the Sign In form and its credential executor. Skipped entirely when a session is present.
• Save / Load Session — the join where both paths converge. Fresh path saves the flow state into a new session and emits the handle (→ Set-Cookie); present path loads the saved flow state into the execution context. Its presence is what makes the flow session-managed.
• Authorization — a mandatory post-join step; runs on every execution because it sits after the join.
• Auth Assertion Generator — builds the final assertion; this is where the runtime assurance check is enforced (see below).
• END.

The skip target is the join, so everything between Check SSO Session's present port and the join is skipped on SSO, and everything after the join always runs. Moving the join is the author's lever for what SSO skips. A flow without a Save / Load Session node is sessionless.

---

Data model

Three lifecycles pull in different directions, so storage is split rather than one fat row: a lean, hot SESSION row; a write-once SESSION_AUTH_CONTEXT sibling for the durable auth-event facts; and transient per-execution state, which stays in the flow engine's execution store and is never persisted to the session.

SESSION (lean, hot — read on every resolve, frequently touched):

Field	Notes
session_id	internal PK, never leaves the server
subject_id	the authenticated user
flow_id	the flow that owns the session = the SSO group key; read on every SSO check
flow_version	skip-compatibility guard; on the hot path
handle_id, handle_issued_at, handle_expires_at	transport-decoupled reference; handle_id unique
binding	cookie-strict for browser; key-bound later (native)
assurance_level, authenticated_at	aggregate facts kept on the hot row for cheap policy checks (acr/max_age) without loading the context
created_at, last_active_at	last_active_at is rewritten at most once per configured window (e.g. 1 min); requests inside the window don't trigger a write
idle_expires_at, absolute_expires_at	lifetimes (enforcement out of scope; fields present)
state	ACTIVE (ENDED later)
version	optimistic lock for concurrent (multi-tab) writes

Identity is per-(subject, flow, agent), enforced by handle-anchored reuse (the Save / Load Session node reuses whatever session the incoming handle resolves to).

SESSION_AUTH_CONTEXT (sibling, 1:1 by session_id, encrypted at rest, lazy-loaded). Written once on fresh auth and read only when a reused session is loaded — not touched by activity updates, so it is encrypted and erasable independently of the hot row.

Field	Notes
session_id	PK / FK → SESSION, 1:1
completed_steps	per-node auth-event facts (structure below)
snapshot_claims	optional — only the minimal claims safe to snapshot; mutable attributes are not copied here (revoke-on-change instead)
context_version	serialization/schema (envelope) version of the stored context — lets the loader decode/migrate older payload formats. Distinct from flow_version.

// completed_steps
[
  { "node_id": "identifier-password", "executor": "AUTHENTICATION",
    "amr": "pwd", "completed_at": "...", "claims": { /* sanitized */ } }
]

• Keyed by node_id so the engine can mark steps satisfied and hydrate the execution context on load.
• Sanitized — established assertions only; never passwords, OTP secrets, raw inputs, or tokens. Bounded (hard size cap).
• Always read/written as a unit and never queried per step, so it is stored as a single serialized value encrypted at rest — not a per-step child table or a queryable JSON column.
• Hot-path reads (resolve, SSO-check, activity touch) hit SESSION only; the context is read only on the load path and written in the same transaction as its SESSION.

Apps sharing a flow_id are one SSO group. No new group entity — the flow is the group.

---

Architecture

Session resolution — a SessionResolver reads the handle from the request, loads the session, and returns it only if ACTIVE, within deadlines, and binding-valid. Transport is an interface: the cookie carrier is one implementation; a native/key-bound carrier plugs in later without touching node logic.

The two nodes map onto the existing flow engine (task-execution nodes + executors, branching via the engine's conditional-edge mechanism):

• Check SSO Session (SessionCheckExecutor) — resolves the handle and tests live and session.flow_id == current flow_id and flow_version compatible and binding valid; routes present vs absent and stashes the resolved session reference for the join node. Detects and routes only — it does not hydrate state.
• Save / Load Session (SessionExecutor) —
  • Fresh path: build the authenticated context from the execution context, create the session, generate the handle and bind it, and return it so the handler sets the (per-flow) cookie.
  • Present path: load the authenticated context into the execution context (authenticated flag, subject, loaded steps' claims), then update last_active_at only if the configured update window has elapsed. Idempotent under retries; writes use the optimistic version.

Flow-version guard — on load, if session.flow_version ≠ the current definition version, treat as no-skip and run full authentication; never resume against a changed graph.

Per-flow cookie — a browser may hold sessions for more than one flow, so the cookie name is keyed per flow_id so one flow's cookie does not overwrite another's.

Runtime assurance check (Auth Assertion Generator) — at assertion build, verify the assurance accumulated in this execution (from executed nodes or the loaded snapshot) meets the flow's contract and the request's acr_values / max_age; otherwise step up or fail with interaction_required. This is the backstop that catches a loaded session whose saved assurance is below what the flow needs.

Open items

Open / deferred

• Identity-attribute & standing changes → revoke affected sessions on the change event (leave a subject-scoped revocation seam now).
• Partial reuse of still-valid steps on flow-version mismatch.

---

Any suggestions to improve the proposal is appreciated.

[janakamarasena]

Keeping other aspects aside, I am wondering whether SSO should be part of the ochestratable flow or a simple config to enable SSO. While having the ochestratable flow will be useful for super users I feel it might add an unnecessary cognitive overhead in most cases. I guess my question is what sort orchestration needs can be there with regard to sessions?

also wrt the stated trade off SSO works only across identical flows. Two apps whose flows merely overlap (e.g. u+p vs u+p+MFA) will not SSO — they are different groups. Can you explain the reasoning behind having an exact flow match as oppose to assurance level matches?

[madurangasiriwardena]

Great questions — both really ask whether the flow is the right home for this.

Flow-orchestrated vs. a simple "enable SSO" toggle

Agreed that hand-wiring nodes shouldn't be the default experience. The intent isn't for every app author to place a Check-SSO / Session node — the common case is served by shipping default flows with SSO already wired, so a typical app just selects that flow (config-like), and only power users touch the graph.

The reason it lives in the flow rather than a flat flag is that "reuse a session" is really "which parts of this flow may be skipped," which is inherently flow-shaped. A boolean can't express things that genuinely come up with sessions:

• What to skip vs. always run — the join placement decides this: credentials are skipped on reuse, but steps after the join (e.g. authorization/consent) run on every execution. Moving the join is the author's lever.
• Partial reuse within a flow — because the session is checked and loaded at chosen points in the graph, a flow can reuse some steps while still running others every time (e.g. skip password entry but always run a step placed after the join).

So the model keeps expressiveness for the cases that need it while default templates keep the overhead near zero for the common case.

Exact-flow match vs. assurance-level match

In practice this constraint lines up with how apps are configured — apps that should SSO together are typically set up with the same auth flow, so exact-match already covers the common case.

Beyond that, exact-flow is unambiguously correct with no cross-flow reasoning: the session was established by this exact flow, so replaying it into the same flow reproduces the same steps, assurance, and claims. Assurance-level matching would need two things we deliberately deferred:

1. a comparable, well-defined assurance / acr model across flows, and
2. partial replay — reusing the steps two flows share and running only the extra ones. This also raises a step-mapping problem: node ids differ across flows, so "which completed steps satisfy the target flow?" isn't obvious.

[ThaminduDilshan]

Recently we have onboarded a interceptor concept (design discussion: #2375) that allows attaching a interceptor to the flow nodes or requests. IMO SSO use case best fits to be a interceptor rather than adding as a flow executor.

Currently we have defined 4 modes for the interceptors (PRE_REQUEST, PRE_NODE, POST_NODE, POST_REQUEST). Maybe we can think of introducing a new mode like PRE_FLOW for the SSO requirement that gets engaged before executing the flow.

[madurangasiriwardena]

Flow-centric browser SSO — architecture

Core idea

SSO is flow-centric: a session belongs to exactly one authentication flow (keyed by flow_id). Two apps SSO with each other iff they're configured with the same auth flow. Each flow gets its own cookie, tid_sso_<16hex> (session.CookieName(flowID)), so sessions for different flows never collide in the browser.

The flow graph gains two node types, used as one or more checkpoint pairs:

• SSO-Check (ssoCheckExecutor, utility node) — resolves whether a live, compatible session already holds this checkpoint and routes Available → skip this stage / Unavailable → authenticate this stage.
• Session (sessionExecutor, authentication node) — the join where the SSO and fresh-auth branches converge. On the fresh path it saves the checkpoint's context (establishing the session if needed) and mints a handle; on the SSO path it loads the saved context so downstream nodes continue authenticated.

A flow may contain multiple SSO-Check/Session checkpoint pairs (e.g. password as one checkpoint, step-up/MFA as another). Each SSO-Check binds to its Session node via a checkpointRef node property, and the checkpoint id is that Session node's id. All checkpoints of one login share a single session per flow execution — the first Session node to run establishes it (idempotently, keyed by the flow execution id), and later checkpoints on any branch attach their own snapshot to that same session. So each stage can be skipped independently on reuse.

Storage model (runtime DB)

Split so the hot path stays lean and the heavier state is loaded only on restore:

Table	Role	Notes
SSO_SESSION	Lean session row	subject_id, flow_id, flow_version, flow_execution_id, handle_id, authenticated_at, idle_expires_at, absolute_expires_at, state, optimistic version. Read on every resolve/touch. One row per establishing flow execution (unique on flow_execution_id).
SSO_SESSION_CONTEXT	Per-checkpoint session context (replay state)	Keyed by (session_id, deployment_id, checkpoint_id) — one row per checkpoint. CONTEXT (JSON, encrypted at rest) + context_version. Loaded only on the SSO restore path; never touched by activity updates.
SSO_SESSION_PARTICIPANT	1:many apps that used the session	PK (session_id, deployment_id, app_id) + first_joined_at / last_active_at. Basis for future session-wide logout/revocation.

Note: sessions are currently stored in the RDBMS (runtime DB). In later stages we'll evaluate other storage options (e.g. an in-memory / distributed store) to optimize for high-load scenarios.

Session lifecycle

Session lifetime is governed by two deadlines, both configurable (product config, session: block):

• Idle timeout — sliding inactivity window, refreshed on each touch (default 30m).
• Absolute timeout — fixed hard cap on total lifetime (default 8h).

The resolver rejects a session past either deadline. (The session handle itself carries no expiry — handle rotation is a follow-up; see below.)

Engine-agnostic integration (key design decision)

The flow engine now lives in the reusable pkg/thunderidengine package. SSO is a product feature, so it plugs in through the engine's generic seams rather than adding anything SSO-specific to the engine contract:

• SSO inputs — the inbound handle and the flow id/version are carried on the request context.Context, so they are transient (never persisted) and never appear on the engine's node context.
• Handle output — the Session node returns the minted handle on the engine's generic AdditionalData channel, and the product transport layer reads it to set the per-flow cookie. No SSO-specific field is added to the engine response.
• Session config lives in product config, not the engine's flow config.

What gets persisted (the session context)

On the fresh path the Session node writes a per-checkpoint session context — the state needed to reconstruct the subject and continue the flow when the checkpoint is later reused:

• Authenticated user — the resolved AuthUser stored as-is, including its materialized attributes (the subject's full stored profile, resolved without an attribute filter at save time). On restore it's replayed verbatim, so downstream reads the same subject and attributes this flow resolved.
• Runtime values — the flow's runtime data, persisted in full apart from a deny-list of request-scoped keys that would otherwise leak the establishing app's request onto a different app joining via SSO — requested_permissions, required_essential_attributes, required_optional_attributes, required_locales, applicationId, clientId, authorizationRequestId — plus the transient SSO control keys. This deny-list is a stopgap until the runtime-data classification below.
• Completed authentication steps — which auth steps the flow finished, with the executor name and completion time; used to describe the authentication event on restore.

A sample session context (CONTEXT) for a local user:

{
  "runtimeData": {
    "userID": "019f35c3-bce7-7306-847b-6ce57bc172d6",
    "user_attributes_cache_ttl_seconds": "4260"
  },
  "authUser": {
    "entityReferenceToken": null,
    "entityReference": {
      "entityId": "019f35c3-bce7-7306-847b-6ce57bc172d6",
      "entityCategory": "user",
      "entityType": "Person",
      "ouId": "01900000-0000-7000-8000-000000000001"
    },
    "attributeToken": null,
    "attributes": {
      "attributes": {
        "email": {
          "value": "maduranga@wso2.com",
          "assuranceMetadataResponse": { "isVerified": false }
        },
        "family_name": {
          "value": "Siriwardena",
          "assuranceMetadataResponse": { "isVerified": false }
        },
        "given_name": {
          "value": "Maduranga",
          "assuranceMetadataResponse": { "isVerified": false }
        },
        "phone_number": {
          "value": "+94771234567",
          "assuranceMetadataResponse": { "isVerified": false }
        },
        "username": {
          "value": "maduranga",
          "assuranceMetadataResponse": { "isVerified": false }
        }
      }
    }
  },
  "completedSteps": {
    "basic_auth": {
      "executor": "CredentialsAuthExecutor",
      "status": "COMPLETE",
      "completedAt": 1783313922
    }
  }
}

Each SSO-issued token still gets a freshly rebuilt ATTRIBUTE_CACHE (via auth_assert), so the session never depends on a prior cache row surviving.

Deferred to the next stage — storage optimization & data classification

Persisting the full AuthUser and near-full runtime data is deliberate for now: we're validating behavior first and keeping the write path simple. Two refinements are planned:

• Attribute minimization / re-resolution — instead of materializing the subject's whole profile into every checkpoint, persist only what can't be re-derived and re-resolve a local subject's attributes from the entity store per joining app (a federated user's IdP claims still need persisting, since they aren't synced into the local entity). This also keeps each CONTEXT within its size cap.
• Runtime-data durability classification — a proper classification for runtime-data keys (identity/policy kept; request-scoped/transient/secret dropped) declared at each key's definition, replacing today's local deny-list. Until then we blindly persist the runtime data and filter only the known-problematic keys.

[madurangasiriwardena]

This is tracked and implemented with #3672