Skip to content

docs: Enterprise SSO setup guide#588

Open
Pitiakova wants to merge 2 commits intomainfrom
val-sso-docs-for-enterprise
Open

docs: Enterprise SSO setup guide#588
Pitiakova wants to merge 2 commits intomainfrom
val-sso-docs-for-enterprise

Conversation

@Pitiakova
Copy link
Copy Markdown
Contributor

@Pitiakova Pitiakova commented Apr 27, 2026

Summary

  • Adds a new dedicated page docs/webapp/enterprise-sso.mdx for Enterprise SSO (SAML 2.0) setup
  • Covers: prerequisites, IdP SAML config, DNS TXT verification, provider lifecycle, enforcement, and rollout checklist
  • Cross-links added in organization-security.mdx and webapp/index.mdx
  • SSO is clearly marked Enterprise-only throughout
  • Doc verified against actual backend code (providers.ts, provision-user.ts, verify-dns.ts, SsoConfiguration.vue)

Test plan

  • Page renders at /docs/webapp/enterprise-sso/
  • Links from organization-security and webapp index resolve correctly

Made with Cursor

Summary by CodeRabbit

  • Documentation
    • Added a comprehensive Enterprise SAML 2.0 SSO setup guide covering IdP configuration, DNS verification, provider activation, first-time provisioning, role assignment, and enforcement options.
    • Updated webapp index and organization security docs to surface Enterprise SSO and link to the new setup guide.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 27, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6cf94097-87b2-4c91-b565-9854a587e6ac

📥 Commits

Reviewing files that changed from the base of the PR and between 0ee4c6a and e75927f.

📒 Files selected for processing (1)
  • apps/docs/src/content/docs/docs/webapp/enterprise-sso.mdx

📝 Walkthrough

Walkthrough

Adds a new Enterprise SAML 2.0 SSO documentation page for Capgo and updates webapp index and organization security docs to reference the new SSO guide. The SSO doc covers IdP config, DNS verification, provider activation, role provisioning, enforcement, and rollout checklist.

Changes

Cohort / File(s) Summary
Enterprise SSO Documentation
apps/docs/src/content/docs/docs/webapp/enterprise-sso.mdx
New page describing SAML 2.0 SSO setup: IdP fields (ACS URL, Entity ID, NameID, stable email claim), adding provider by domain/metadata, DNS TXT ownership verification (_capgo-sso.<domain>), provider statuses (Pending, Verified, Active, Disabled), activation/deactivation, first-time provisioning defaults, identity merge note, enforcement option, and rollout checklist.
Documentation Navigation & Security
apps/docs/src/content/docs/docs/webapp/index.mdx, apps/docs/src/content/docs/docs/webapp/organization-security.mdx
Inserted an “Enterprise SSO” navigation link in webapp index and added an SSO (Enterprise only) item referencing SAML 2.0 and linking to the new SSO setup guide in organization security settings.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Dashboard as Capgo Dashboard
  participant DNS as DNS Provider
  participant IdP as Identity Provider
  participant Auth as Capgo Auth Backend

  User->>Dashboard: Open SSO setup (add provider by domain/metadata)
  Dashboard->>IdP: Display required IdP fields / request SP metadata
  User->>DNS: Publish `_capgo-sso.<domain>` TXT record
  DNS-->>Dashboard: DNS TXT visible to Capgo verification
  Dashboard->>Auth: Verify domain ownership (check DNS)
  Auth-->>Dashboard: Domain status = Verified
  Dashboard->>Auth: Activate provider
  User->>Auth: Login via SSO (redirect to IdP)
  Auth->>IdP: SAML request (ACS, EntityID, NameID)
  IdP-->>Auth: SAML response (assertion, stable email)
  Auth->>Auth: Provision/merge identity, assign org role
  Auth-->>User: Authentication complete (session established)
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A rabbit hops to docs anew,
SAML seeds and DNS clues,
Domains verified, providers wake—
Roles assigned, no steps to take.
Hooray for secure, smooth SSO! 🥕🔐

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: adding Enterprise SSO setup documentation.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch val-sso-docs-for-enterprise

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

- Add enterprise-sso.mdx (SAML setup, DNS, lifecycle)
- Link from webapp intro and organization security overview

Made-with: Cursor
@Pitiakova Pitiakova force-pushed the val-sso-docs-for-enterprise branch from 0c65025 to 0ee4c6a Compare April 27, 2026 16:39
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/docs/src/content/docs/docs/webapp/enterprise-sso.mdx`:
- Around line 85-89: In the "Step 4 - Activate the provider" section update the
wording so it matches the status reference table: either replace the verb
"Deactivate" with "Disable" or add a clarifying sentence such as "Deactivating a
provider moves its status to Disabled" so readers can map the action to the
resulting status; apply the same change consistently in the status reference
table section (the block labeled status reference / provider status) so both the
action text and the status label use the same terminology.
🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8aaaac13-4465-49f2-8662-647d3f737e66

📥 Commits

Reviewing files that changed from the base of the PR and between 3150abc and 0ee4c6a.

📒 Files selected for processing (3)
  • apps/docs/src/content/docs/docs/webapp/enterprise-sso.mdx
  • apps/docs/src/content/docs/docs/webapp/index.mdx
  • apps/docs/src/content/docs/docs/webapp/organization-security.mdx

Comment thread apps/docs/src/content/docs/docs/webapp/enterprise-sso.mdx Outdated
- Clarify the process for deactivating providers in the dashboard.
- Specify the implications of setting a provider to Disabled and the reactivation process.
@sonarqubecloud
Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant