Add Single Sign-On documentation

.vale/styles/ThunderID/TitleCaseTitles.yml

@@ -33,6 +33,7 @@ exceptions:
   - Per-Cache
   - act
   - Sign-In
+  - Sign-On
   - Sign-Out
   - Sign-Up
   - iOS

docs/content/guides/guides/flows/single-sign-on.mdx

@@ -0,0 +1,102 @@
+---
+title: Single Sign-On for Flows
+sidebar_position: 6
+persona: iam
+description: Add Single Sign-On (SSO) to authentication flows so users skip steps they have already completed, using the Check SSO Session and Save / Load Session nodes in the Console Flow Builder.
+---
+
+import {SsoSingleStepDiagram} from '../../../../src/components/SsoFlowDiagram';
+
+# Single Sign-On for Flows
+
+Single Sign-On (SSO) lets a user authenticate once and then reuse that authentication across applications, without repeating steps they have already completed. <ProductName /> provides SSO as a building block inside authentication flows: you add two nodes to a flow, and the flow skips authentication steps whenever a valid session already covers them.
+
+This guide explains how flow SSO works, describes the two SSO nodes, and shows how to add SSO to a flow. For the underlying session model, see [Sessions and Single Sign-On](../../key-concepts/authentication/sessions.mdx).
+
+## How Single Sign-On Works
+
+Flow SSO is **flow-centric**: a session belongs to exactly one flow. Every application that authenticates through the same flow shares that flow's session, so the second application reuses the first application's authentication instead of prompting the user again. Two different flows never share a session.
+
+A flow SSO session has three characteristics:
+
+- **Per-flow.** The flow is the grouping key. The session covers only applications that use the same flow.
+- **Browser-scoped.** <ProductName /> references the session with a per-flow cookie that the browser sends on each request. Flow SSO applies to browser-based authentication.
+- **Checkpoint-based.** A **checkpoint** is the authentication that SSO can skip. You define it with a **Check SSO Session** node and a **Save / Load Session** node, and the checkpoint covers the steps between them. On a later sign-in, the flow reuses the checkpoint instead of prompting for those steps.
+
+## Single Sign-On Nodes
+
+You build flow SSO from two executor nodes in the Console Flow Builder. You place them around each authentication step you want to make skippable.
+
+### Check SSO Session
+
+The **Check SSO Session** node decides whether the following authentication step can be skipped. Place it immediately before the step. It answers the question: *Can the following authentication be skipped by reusing the existing session?* In a flow definition, it is a `TASK_EXECUTION` step that runs the `SSOCheckExecutor`.
+
+The node has two outcomes:
+
+| Outcome | Link label | Meaning |
+|---|---|---|
+| Success | **Skip to** | A valid session already covers this step. The flow skips the step and continues from the target node. |
+| Failure | **Authenticate** | No reusable session covers this step. The flow runs the full authentication step. |
+
+### Save / Load Session
+
+The **Save / Load Session** node is the checkpoint. Place it at the point where the authentication you want to make skippable completes: the join point that both the **Skip to** and **Authenticate** paths lead to. In a flow definition, it is a `TASK_EXECUTION` step that runs the `SessionExecutor`.
+
+The node performs one of two actions automatically, based on the request:
+
+- On a fresh sign-in, it establishes the session (or attaches to the session an earlier checkpoint in the same sign-in created) and saves the checkpoint for the authentication just completed.
+- On a reused session, it loads the saved checkpoint so downstream nodes read the authenticated user without re-running the steps it covers.
+
+## Add Single Sign-On to a Flow
+
+To make a group of authentication steps skippable, wrap them with a **Check SSO Session** node before the first step and a **Save / Load Session** node at the join point where they complete. The group can be a single step or multiple steps.
+
+The following diagram shows a password step made skippable. The **Skip to** path bypasses the prompt and credential check; the **Authenticate** path runs them. Both paths converge on **Save / Load Session**.
+
+<SsoSingleStepDiagram />
+
+To build this flow:
+
+1. Open the flow in the **Console Flow Builder**.
+2. Add a **Check SSO Session** node after the entry point, before the first authentication step you want to make skippable.
+3. Connect the **Authenticate** outcome to the first node of that authentication (for example, the credentials prompt).
+4. Add a **Save / Load Session** node after the authentication steps complete.
+5. Connect the **Skip to** outcome of **Check SSO Session** directly to the **Save / Load Session** node.
+6. Connect the final node of the authentication to the same **Save / Load Session** node, so both paths converge.
+7. Continue the flow from **Save / Load Session** to the remaining nodes (for example, authorization and the Auth Assertion Generator).
+
+The first time a user signs in, the flow takes the **Authenticate** path and **Save / Load Session** establishes the session. On the next sign-in through the same flow, **Check SSO Session** finds the session and takes the **Skip to** path.
+
+## Configure Session Lifetime
+
+Two timeouts bound every flow SSO session:
+
+- **Idle timeout**: the maximum inactivity period. The idle deadline moves forward on each use of the session, so an active session stays alive. The default is 30 minutes.
+- **Absolute timeout**: the maximum total lifetime, fixed when the session is created and never extended. The default is 8 hours.
+
+A session expires when it passes either deadline. After expiry, **Check SSO Session** takes the **Authenticate** path and the user signs in again.
+
+Set the timeouts in the `session` server-config resource. In a source checkout, use `backend/cmd/server/config/resources/server_configs/session.yaml`; in a packaged distribution, use `<THUNDERID_HOME>/config/resources/server_configs/session.yaml`. Durations are in seconds. A value of `0` uses the default.
+
+```yaml
+name: session
+value:
+  idleTimeoutSeconds: 1800      # 30 minutes
+  absoluteTimeoutSeconds: 28800 # 8 hours
+```
+
+The idle timeout must not exceed the absolute timeout.
+
+## Session Cookie
+
+<ProductName /> references each flow SSO session with a per-flow cookie named `tid_sso_<hash>`, where `<hash>` is derived from the flow identifier. A separate cookie per flow keeps one flow's session from affecting another. The cookie carries only an opaque handle, never user data, and its attributes follow browser security best practices:
+
+- `HttpOnly`, so client-side scripts cannot read it.
+- `SameSite=Lax`.
+- `Secure`, when the server runs over TLS.
+
+The cookie lifetime matches the absolute session timeout.
+
+## Current Scope and Limitations
+
+- Flow SSO applies to **browser-based** authentication, because it relies on the cookies.

docs/content/guides/key-concepts/authentication/sessions.mdx

@@ -0,0 +1,42 @@
+---
+title: Sessions and Single Sign-On
+sidebar_position: 2
+description: Understand how {{ProductName}} sessions work and how flow Single Sign-On (SSO) lets users reuse authentication across applications.
+---
+
+# Sessions and Single Sign-On
+
+A session records that a user authenticated, so <ProductName /> can trust that authentication again later without prompting the user to repeat it. Single Sign-On (SSO) builds on sessions: when a user has a valid session, <ProductName /> reuses it and skips the steps the session already covers.
+
+This page explains the session model and how SSO applies to authentication flows. To add SSO to a flow, see [Single Sign-On for Flows](../../guides/flows/single-sign-on.mdx).
+
+## Flow-Centric Sessions
+
+<ProductName /> ties each SSO session to a single flow. The flow is the grouping key: every application that authenticates through the same flow shares that flow's session, and two different flows never share a session.
+
+Because the flow is the grouping key, you can group sessions by the security category of the applications. Assign applications that share a security category to the same flow so they reuse one authentication. Put applications in a more sensitive category on a separate flow, so a session established for a lower-category application never signs the user in to a higher-category one.
+
+## Checkpoints
+
+A **checkpoint** is the authentication that SSO can skip and reuse. You define it with a pair of nodes: a **Check SSO Session** node marks where the reusable authentication begins, and a **Save / Load Session** node marks where it ends. The checkpoint covers the authentication steps between them.
+
+On a fresh sign-in, the flow runs those steps and saves the checkpoint under the session. On a later sign-in, the flow reuses the checkpoint and skips the steps it covers. If the checkpoint has expired, the user completes the steps again.
+
+## Session Lifetime
+
+Two independent timeouts bound every session:
+
+| Timeout | Behavior | Default |
+|---|---|---|
+| Idle | Moves forward on each use of the session, so an active session stays alive. The session expires after this much inactivity. | 30 minutes |
+| Absolute | Fixed when the session is created and never extended. The session expires this long after creation regardless of activity. | 8 hours |
+
+A session expires when it passes either deadline. After expiry, the next sign-in through the flow authenticates the user again. An administrator configures both timeouts in the server configuration. See [Configure Session Lifetime](../../guides/flows/single-sign-on.mdx#configure-session-lifetime).
+
+## Browser Scope
+
+Flow SSO applies to browser-based authentication. <ProductName /> references each session with a per-flow cookie that carries only an opaque handle, never user data. Because the cookie is the reference, SSO reuse happens within a browser: a user who authenticates in one browser does not gain a session in another.
+
+## Related
+
+- [Single Sign-On for Flows](../../guides/flows/single-sign-on.mdx) shows how to add the SSO nodes to a flow in the Console Flow Builder.

docs/sidebars.ts

@@ -557,6 +557,11 @@ const sidebars: SidebarsConfig = {
               id: 'guides/guides/flows/build-a-flow',
               label: 'Build a Flow',
             },
+            {
+              type: 'doc',
+              id: 'guides/guides/flows/single-sign-on',
+              label: 'Single Sign-On',
+            },
             {
               type: 'doc',
               id: 'guides/guides/flows/advanced-configurations',
@@ -849,6 +854,11 @@ const sidebars: SidebarsConfig = {
               id: 'guides/key-concepts/authentication/integration-models',
               label: 'Integration Models',
             },
+            {
+              type: 'doc',
+              id: 'guides/key-concepts/authentication/sessions',
+              label: 'Sessions and Single Sign-On',
+            },
           ],
         },
         {

docs/src/components/SsoFlowDiagram.tsx

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import React from 'react';
+
+export function SsoSingleStepDiagram(): React.ReactElement {
+  return (
+    <figure
+      className="flow-node-diagram"
+      role="img"
+      aria-label="Single-step Single Sign-On flow: Start leads to Check SSO Session. The Skip to path goes straight to Save / Load Session; the Authenticate path goes through Collect Credentials and Credentials Auth before reaching Save / Load Session. Save / Load Session then leads to Auth Assertion Generator and End."
+    >
+      <svg
+        viewBox="0 0 910 180"
+        style={{width: '100%', overflow: 'visible', display: 'block', fontFamily: 'inherit'}}
+        aria-hidden="true"
+      >
+        <defs>
+          <marker id="sso1-arr" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+            <polygon points="0 0, 8 3, 0 6" style={{fill: 'context-stroke'}} />
+          </marker>
+        </defs>
+
+        {/* ── Nodes ──────────────────────────────────────────────────── */}
+        <rect x="12" y="33" width="60" height="34" rx="17" className="fnd-node fnd-node--start" />
+        <text x="42" y="50" textAnchor="middle" dominantBaseline="central" className="fnd-label fnd-label--light">
+          Start
+        </text>
+
+        <rect x="96" y="28" width="132" height="44" rx="8" className="fnd-node fnd-node--task" />
+        <text x="162" y="50" textAnchor="middle" dominantBaseline="central" className="fnd-label">
+          Check SSO Session
+        </text>
+
+        <rect x="470" y="28" width="140" height="44" rx="8" className="fnd-node fnd-node--task" />
+        <text x="540" y="50" textAnchor="middle" dominantBaseline="central" className="fnd-label">
+          Save / Load Session
+        </text>
+
+        <rect x="648" y="28" width="150" height="44" rx="8" className="fnd-node fnd-node--task" />
+        <text x="723" y="44" textAnchor="middle" dominantBaseline="central" className="fnd-label">
+          Auth Assertion
+        </text>
+        <text x="723" y="58" textAnchor="middle" dominantBaseline="central" className="fnd-label">
+          Generator
+        </text>
+
+        <rect x="832" y="33" width="60" height="34" rx="17" className="fnd-node fnd-node--end" />
+        <text x="862" y="50" textAnchor="middle" dominantBaseline="central" className="fnd-label fnd-label--light">
+          End
+        </text>
+
+        <rect x="250" y="120" width="140" height="40" rx="6" className="fnd-node fnd-node--prompt" />
+        <text x="320" y="140" textAnchor="middle" dominantBaseline="central" className="fnd-label">
+          Collect Credentials
+        </text>
+
+        <rect x="410" y="120" width="120" height="40" rx="6" className="fnd-node fnd-node--task" />
+        <text x="470" y="140" textAnchor="middle" dominantBaseline="central" className="fnd-label">
+          Credentials Auth
+        </text>
+
+        {/* ── Arrows ─────────────────────────────────────────────────── */}
+        <line x1="72" y1="50" x2="92" y2="50" className="fnd-edge" markerEnd="url(#sso1-arr)" />
+
+        {/* Check → Save (Skip to) */}
+        <line x1="228" y1="50" x2="466" y2="50" className="fnd-edge fnd-edge--success" markerEnd="url(#sso1-arr)" />
+
+        {/* Check → Collect Credentials (Authenticate) */}
+        <path d="M 162,72 V 140 H 246" className="fnd-edge fnd-edge--failure" markerEnd="url(#sso1-arr)" />
+
+        {/* Collect Credentials → Credentials Auth */}
+        <line x1="390" y1="140" x2="406" y2="140" className="fnd-edge" markerEnd="url(#sso1-arr)" />
+
+        {/* Credentials Auth → Save (rejoin) */}
+        <path d="M 530,140 H 540 V 74" className="fnd-edge" markerEnd="url(#sso1-arr)" />
+
+        {/* Save → Auth Assertion Generator */}
+        <line x1="610" y1="50" x2="644" y2="50" className="fnd-edge" markerEnd="url(#sso1-arr)" />
+
+        {/* Auth Assertion Generator → End */}
+        <line x1="798" y1="50" x2="828" y2="50" className="fnd-edge" markerEnd="url(#sso1-arr)" />
+
+        {/* ── Edge labels ────────────────────────────────────────────── */}
+        <text x="347" y="42" textAnchor="middle" dominantBaseline="central" className="fnd-edge-label fnd-edge-label--success">
+          Skip to
+        </text>
+        <text x="170" y="104" dominantBaseline="central" className="fnd-edge-label fnd-edge-label--failure">
+          Authenticate
+        </text>
+      </svg>
+    </figure>
+  );
+}