Skip to content

feat(web): SSO & SCIM settings tab and customer docs - #2722

Open
Makisuo wants to merge 13 commits into
t3/enterprise-sso-scimfrom
t3/enterprise-sso-scim-web
Open

Makisuo wants to merge 13 commits into
t3/enterprise-sso-scimfrom
t3/enterprise-sso-scim-web

Conversation

@Makisuo

@Makisuo Makisuo commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Stack: 1/2 #2721 (API, tables, webhook) > 2/2 (this PR)

What

  • Settings, SSO & SCIM tab (?tab=sso, under Access): domains with their TXT record and Verify, connect or edit a SAML/OIDC identity provider (only verified domains offered), the values to paste into the IdP, a Require SSO switch with a confirm, break-glass members (picker limited to members on the SSO domains), SCIM set-up with the token shown once in a dialog and cleared from state on close, pause/resume, rotate (confirm), remove, and role mapping rows (IdP group to Admin, Engineer, Member or Analyst) with reorder, save and discard.
  • Non-admins see the tab read-only. Orgs without the Enterprise plan see a contact-sales notice.
  • /lab/sso renders every state over fixtures (?state=not-entitled|empty|pending|connected|enforce|configured|token|member).
  • Customer docs: apps/landing/src/content/docs/reference/single-sign-on.md (setup, SCIM for Okta and Entra ID, role mapping, deprovisioning, troubleshooting).

Built from the kit only; no new kit components or icons.

Screenshots (/lab/sso)

Not entitled Pending domain
Connected, not enforced Require SSO confirm
Fully configured SCIM token, shown once (fixture token)
Read-only member Dark
Mobile, pending Mobile, configured

Verification

  • sso.scene.test.ts (10): not-entitled notice, empty state, read-only member, TXT record shown, SAML form checked before submit, enforce confirm, token revealed once and cleared on close, role mapping save payload.
  • All settings tests (302) and src/lab/registry.test.ts pass; web typecheck clean; oxlint -c .oxlintrc.effect.json and plain oxlint clean on every touched file; ui:patterns:check OK.
  • Screenshots above: headless Chromium against the local dev server, light, dark and 390px wide.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Devin Review

A new Settings tab for Enterprise orgs: verify domains by DNS TXT record,
connect a SAML or OIDC identity provider, require SSO with a confirm and a
break-glass list, set up SCIM with a token shown once, rotate, pause or remove
it, and map IdP groups to roles. Non-admins see it read-only; orgs without the
Enterprise plan see a contact-sales notice. /lab/sso renders every state over
fixtures. Docs: reference/single-sign-on.
@maple-review-bot

This comment has been minimized.

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 49a2bc84-13f0-4251-a3f8-0805ff143461

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@Makisuo Makisuo added the preview:web Deploy a Workers-only PR preview (no ingest/Electric); see docs/pr-previews.md label Nov 16, 2026

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Devin Review found 3 potential issues.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

Devin Review

Comment thread apps/web/src/page/settings/sso/view.ts Resolved

@maple-review-bot maple-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

3 inline notes from Maple's review. The score and summary are in the review comment above.

Comment thread apps/web/src/page/settings/sso/view.ts Resolved
Comment thread apps/web/src/page/settings/sso/view.ts Resolved
… says why Connect is disabled

- Without the plan, admins can still relax Require SSO, pause or remove SCIM,
  remove the connection and break-glass members; setting up stays gated.
- A failed member list loads again on retry, revisit and reopening the
  break-glass dialog.
- Add member waits for a connection; an empty picker says whether nobody is on
  the SSO domains or everyone already has access.
- The connection dialog names what the draft is missing next to its submit.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

🍁 Maple PR preview

Warning

The latest preview deployment did not complete. The Alchemy deploy outcome was skipped; any earlier preview should be treated as stale.

Commit 9a6064f · View workflow run

@maple-review-bot

This comment has been minimized.

@maple-review-bot maple-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

2 inline notes from Maple's review. The score and summary are in the review comment above.

Comment thread apps/web/src/page/settings/sso/view.ts Resolved
…e eligibility

The member list loads every page instead of the first 100, and the picker no
longer filters on the primary email: any verified address on the SSO domains
qualifies, and the API's refusal names the reason.
@maple-review-bot

maple-review-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Maple review

🟢 Confidence 10/10 · safe to merge. The pagination fix is verified and the tab is pinned by scene tests; the earlier read-only note still keys only on canManage.
1 note · tests covered · risk medium

Adds the SSO & SCIM settings tab (domains, identity provider, enforcement, break-glass members, SCIM token and role mappings) built from the kit, plus its /lab/sso states. Entitlement and role gating match the API's own rules; safe to merge.

  • ?tab=sso settings tab for domains, identity provider, enforcement, break-glass members and SCIM
  • FetchSsoMembers reads every Clerk membership page instead of the first
  • The SCIM token is shown once in a dialog and cleared when it closes
  • /lab/sso renders eight states over fixtures

Still open from earlier reviews

Fixed since the last review

  • ✅ F6 · Break-glass picker only offers the first 100 members

dca6845 · What was checked, coverage and telemetry details are on the Maple / review check. Reply "won't fix" to dismiss a finding, or mention @maple-review-bot to ask about one.

@Makisuo

Makisuo commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

@maple-review-bot won't fix F4: the tab derives canManage from the session grants the same way the other settings tabs do (Policy.has(grantsOf(model), ...)), so a failed session read degrades to read-only, which is the safe direction; every write is still authorized by the API (sso:manage). Also in 9a6064f: the rotate confirm now says the old token keeps working for Clerk's short grace period.

@maple-review-bot

Copy link
Copy Markdown

Checked settings/update.ts:291 (Sso.init(Policy.has(grantsOf(model), "sso:manage"))), grantsOf at update.ts:67-72 (empty grants until the session answers, empty on failure), sso/update.ts:222-250, and the page's role-unknown handling in settings/view.ts:255-277.

You're right about the derivation and about writes being safe — I'm not disputing either. But F4 was only about the message, and that half still holds, so I'm leaving it open. The other tabs that derive canManage this way are also listed in ROLE_GATED_TABS, so a failed session read swaps their read-only state for "Couldn't confirm your role, so editing is off. Reload the page to try again.":

// apps/web/src/page/settings/view.ts:259
const ROLE_GATED_TABS: ReadonlySet<SettingsTab> = new Set([
	"general", "members", "billing", "keys", "automation",
])

"sso" isn't in that set and the nav shows the tab regardless of grants (nav.ts:115), so on a failed session read an entitled admin lands on a loaded document and reads view.ts:1274:

...(model.canManage ? [] : [adminOnlyNote(h, ["Only admins can change SSO and SCIM settings."])]),

That tells an admin they lack the role rather than that the role couldn't be read — and the page note that would have said the latter is suppressed by roleUnknownReason returning null at line 272. Same one-line shape as the tabs already there: add "sso" to ROLE_GATED_TABS. Not urgent, but it isn't the same behaviour as the other tabs today.

@Makisuo

Makisuo commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

@maple-review-bot fair, fixed in f3c10df: sso joins ROLE_GATED_TABS, so a failed session read shows the same "Couldn't confirm your role" notice as the other role-gated tabs.

@maple-review-bot

Copy link
Copy Markdown

Note

⏳ Maple is reviewing this pull request at f3c10df. This comment updates with the review when it finishes.

@maple-review-bot

Copy link
Copy Markdown

Checked the head: "sso" is in ROLE_GATED_TABS (view.ts:265) and sso is visible to every Clerk member (nav.ts:115), so a failed session read on that tab now gets the page banner "Couldn't confirm your role, so editing is off" — that part is right.

The tab's own note is unchanged though. initTab passes Sso.init(Policy.has(grantsOf(model), "sso:manage")) (update.ts:291), and grantsOf returns [] when the session read failed (update.ts:67-72), so canManage is false and sso/view.ts:1274 still renders on top of the corrected banner:

...(model.canManage ? [] : [adminOnlyNote(h, ["Only admins can change SSO and SCIM settings."])]),

So the admin reads "editing is off, we couldn't confirm your role" and immediately below it "only admins can change SSO" — the claim F4 was about. The other role-gated tabs avoid exactly this: general, members and billing pass isKnownMember into their view and gate the notice on isKnownMember && !canManage, and automation on canManage(model) || !isKnownMember; kit/members.ts:41-43 states the rule as "while it is unknown or failed, nothing claims the viewer is not an admin."

The smallest fix is the same plumbing: add isKnownMember: isKnownMember(model) to the Sso viewInputs (settings/view.ts:199-208) and gate line 1274 on it. Leaving F4 open on that basis.

This branch is being deployed

1 in progress deployment
pr-preview — f3c10dfe Deployed Nov 16, 2026 by Makisuo via deploy-pr-preview #13040
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

preview:web Deploy a Workers-only PR preview (no ingest/Electric); see docs/pr-previews.md

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant