Add Single Sign-On documentation - #3918
Merged
madurangasiriwardena merged 1 commit intoJul 20, 2026
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughAdds documentation for flow-scoped SSO sessions, checkpoints, cookies, configuration, and browser limitations, plus an accessible flow diagram and navigation entries. ChangesFlow SSO documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/guides/guides/flows/single-sign-on.mdx`:
- Around line 100-102: Update the “Current Scope and Limitations” section in the
SSO guide to explicitly state that multi-checkpoint and step-up authentication
scenarios are not currently supported, alongside the existing browser-based
limitation.
- Line 79: Update the session timeout documentation to reference the actual
session resource path used by the repository, replacing both nonexistent
source-checkout and packaged-distribution paths. Keep the existing guidance for
idleTimeoutSeconds, absoluteTimeoutSeconds, and duration semantics unchanged.
In `@docs/src/components/SsoFlowDiagram.tsx`:
- Around line 21-109: Replace the hand-built SVG in SsoSingleStepDiagram with an
inline Mermaid flowchart in single-sign-on.mdx, preserving the Start, Check SSO
Session, labeled Skip to and Authenticate branches, credential-authentication
path, convergence at Save / Load Session, and final Auth Assertion Generator →
End flow. Remove the SsoSingleStepDiagram component and its import after
updating the MDX usage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 725ba665-4522-423d-9655-cf306c29c638
📒 Files selected for processing (6)
.vale/styles/WSO2-IAM/TitleCaseTitles.yml.vale/styles/config/vocabularies/vocab/accept.txtdocs/content/guides/guides/flows/single-sign-on.mdxdocs/content/guides/key-concepts/authentication/sessions.mdxdocs/sidebars.tsdocs/src/components/SsoFlowDiagram.tsx
Comment on lines
+100
to
+102
| ## Current Scope and Limitations | ||
|
|
||
| - Flow SSO applies to **browser-based** authentication, because it relies on the cookies. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add multi-checkpoint and step-up limitations.
The "Current Scope and Limitations" section lists only the browser-based constraint. The PR objectives note that multi-checkpoint and step-up scenarios are not yet supported. Adding these to the limitations section sets reader expectations and prevents confusion.
📝 Suggested addition
## Current Scope and Limitations
- Flow SSO applies to **browser-based** authentication, because it relies on the cookies.
+- Each flow supports a single checkpoint. Multi-checkpoint and step-up authentication scenarios are not yet supported.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## Current Scope and Limitations | |
| - Flow SSO applies to **browser-based** authentication, because it relies on the cookies. | |
| ## Current Scope and Limitations | |
| - Flow SSO applies to **browser-based** authentication, because it relies on the cookies. | |
| - Each flow supports a single checkpoint. Multi-checkpoint and step-up authentication scenarios are not yet supported. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/content/guides/guides/flows/single-sign-on.mdx` around lines 100 - 102,
Update the “Current Scope and Limitations” section in the SSO guide to
explicitly state that multi-checkpoint and step-up authentication scenarios are
not currently supported, alongside the existing browser-based limitation.
Comment on lines
+21
to
+109
| 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> | ||
| ); | ||
| } |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Use Mermaid instead of hand-built SVG for the flow diagram.
Both the coding guidelines ("Use Mermaid for architecture, flow, sequence, and similar diagrams; do not hand-build diagrams with raw SVG or ASCII art unless Mermaid cannot express the required layout") and the path instructions ("Flag hand-built SVG diagrams... as a major issue") require Mermaid for flow diagrams. This is a standard flowchart with a decision point, two labeled branches, and convergence — Mermaid's flowchart handles this directly.
Secondary concerns resolved by switching to Mermaid:
- Inline
style={{...}}props on lines 30 and 35 violate thesxprop requirement. className-based styling throughout would no longer be needed.fill: 'context-stroke'on line 35 has limited browser support (not in Firefox).- The entire component file and its import in
single-sign-on.mdxline 8 can be eliminated.
As per coding guidelines, use Mermaid for architecture, flow, sequence, and similar diagrams; do not hand-build diagrams with raw SVG or ASCII art unless Mermaid cannot express the required layout. As per path instructions, flag hand-built SVG diagrams as a major issue and ask whether Mermaid should be used instead.
♻️ Proposed Mermaid replacement
Replace the <SsoSingleStepDiagram /> usage in single-sign-on.mdx with an inline Mermaid block and delete SsoFlowDiagram.tsx:
-import {SsoSingleStepDiagram} from '../../../../src/components/SsoFlowDiagram';
-
# Single Sign-On for Flows-<SsoSingleStepDiagram />
+```mermaid
+flowchart LR
+ Start([Start]) --> Check[Check SSO Session]
+ Check -->|Skip to| Save[Save / Load Session]
+ Check -->|Authenticate| Collect[Collect Credentials]
+ Collect --> Auth[Credentials Auth]
+ Auth --> Save
+ Save --> AAG[Auth Assertion Generator]
+ AAG --> End([End]
+```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/src/components/SsoFlowDiagram.tsx` around lines 21 - 109, Replace the
hand-built SVG in SsoSingleStepDiagram with an inline Mermaid flowchart in
single-sign-on.mdx, preserving the Start, Check SSO Session, labeled Skip to and
Authenticate branches, credential-authentication path, convergence at Save /
Load Session, and final Auth Assertion Generator → End flow. Remove the
SsoSingleStepDiagram component and its import after updating the MDX usage.
Sources: Coding guidelines, Path instructions
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
madurangasiriwardena
force-pushed
the
docs/single-sign-on
branch
from
July 15, 2026 06:05
0cbe7d7 to
9989d7e
Compare
Add a guide (Single Sign-On for Flows) and a key-concept page (Sessions and Single Sign-On) covering flow-centric SSO, the Check SSO Session and Save / Load Session nodes, checkpoints, session lifetime, and the session cookie. Add an SsoSingleStepDiagram component for the flow diagram, wire both pages into the sidebar, and extend the Vale title-case exceptions and vocabulary.
madurangasiriwardena
force-pushed
the
docs/single-sign-on
branch
from
July 15, 2026 06:14
9989d7e to
63cc54c
Compare
|
|
||
| To build this flow: | ||
|
|
||
| 1. Open the flow in the **Console Flow Builder**. |
Member
There was a problem hiding this comment.
This might be revisited with @DonOmalVindula 's work. Tagging for reference
ThaminduDilshan
approved these changes
Jul 20, 2026
ThaminduDilshan
added
the
skip-changelog
This was referenced Jul 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
Document flow-centric browser Single Sign-On (SSO) introduced in #3779. Adds user-facing documentation for the feature: how flow SSO works, the two SSO nodes, checkpoints, session lifetime configuration, and the session cookie. Documentation only; no product code changes.
Approach
Two new pages plus supporting docs infrastructure:
guides/guides/flows/single-sign-on.mdx(Single Sign-On for Flows): explains the flow-centric model, describes the Check SSO Session and Save / Load Session nodes (with theirTASK_EXECUTION/SSOCheckExecutor/SessionExecutoridentifiers inline, matching the convention in the other flow docs), walks through adding SSO to a flow, and covers session lifetime and thetid_sso_<hash>cookie.guides/key-concepts/authentication/sessions.mdx(Sessions and Single Sign-On): the underlying session model, checkpoints, flow-centric grouping (including grouping by security category), lifetime, and browser scope.docs/src/components/SsoFlowDiagram.tsx: a hand-built SVG flow diagram reusing the existingfnd-*classes incustom.css(the same pattern asFlowNodeDiagram), rather than Mermaid, which is not enabled in the docs site.docs/sidebars.ts.Sign-Onto the title-case exceptions (alongsideSign-In/Sign-Out/Sign-Up) and[Ss]kippableto the accepted vocabulary. Both pages pass Vale with zero errors and warnings.A checkpoint is described as the pair of nodes (Check SSO Session + Save / Load Session) and the group of authentication steps encapsulated between them.
Related Issues
Related PRs
Checklist
breaking changelabel added.Security checks
Summary by CodeRabbit