Add SSO and Authentication documentation for enterprise users

[samgutentag]

Summary

• Add new "SSO and Authentication" page under Setup & Administration with step-by-step instructions for enterprise organizations setting up SSO
• Address the specific pain point raised in TRUNK-16793: users from large companies with restricted OAuth providers not knowing how to properly set up Trunk with SSO
• Include troubleshooting guide for common SSO issues (wrong email linked, disabled OAuth providers, access management)
• Update existing pages (Account Setup, Managing your Organization, Billing) to cross-link to the new SSO guide

Test plan

• Verify new page renders correctly in GitBook
• Confirm all cross-links between pages work
• Review SSO setup steps with engineering to ensure accuracy
• Confirm list of supported identity providers with the team

Closes TRUNK-16793

🤖 Generated with Claude Code

[claude]

Claude finished @samgutentag's task in 2m 3s —— View job

---

PR Review: SSO and Authentication Documentation

• Gather context and read changed files
• Review new SSO and Authentication page
• Review modified existing pages
• Post inline comments for specific issues
• Provide summary review

---

Summary

This is a well-structured, clearly written documentation addition that addresses a real pain point (TRUNK-16793). The step-by-step setup guide, troubleshooting section, and FAQ are all valuable. The cross-links to existing pages are accurate.

Issues Found

I left 4 inline comments — all minor suggestions, no blocking issues:

1. Line 10 — billing.md link: Link points to the top of the billing page; linking directly to #enterprise-plan would be more helpful.

2. Line 54 — Signup URL mismatch: Says "sign in" but links to /signup. Consider linking to app.trunk.io (the main login page) to avoid confusion for admins who already have accounts.

3. Line 120 — Phrasing nit: "instead of SSO" → "instead of using SSO" reads more naturally.

4. Line 150 — SSO outage FAQ incomplete: The answer only addresses OAuth users; SSO-only users would be completely locked out during an IdP outage, which is worth calling out explicitly.

Other Observations

• The warning block (lines 58–64) is well-placed and addresses the core problem described in TRUNK-16793.
• The cross-links added to billing.md, connecting-to-trunk.md, and managing-your-organization.md are accurate and well-placed.
• The managing-your-organization.md existing line 42 has a pre-existing typo ("under you configured team domain" → "your configured") but that's outside the scope of this PR.

Overall this is solid documentation — approve with the minor suggestions above.

[claude]

The link goes to the top of the billing page. Linking directly to the Enterprise plan section would be more helpful for readers.

Suggested change

	SSO is available on the [Enterprise plan](billing.md). To enable SSO for your organization, contact [sales@trunk.io](mailto:sales@trunk.io).
	SSO is available on the [Enterprise plan](billing.md#enterprise-plan). To enable SSO for your organization, contact [sales@trunk.io](mailto:sales@trunk.io).

[claude]

This says "sign in" but links to /signup. Since this step is for the admin who may already have an account, app.trunk.io/signup can be confusing. Consider linking to the main app URL instead:

Suggested change

	1. Go to [app.trunk.io/signup](https://app.trunk.io/signup) and sign in using your SSO-linked email address.
	1. Go to [app.trunk.io](https://app.trunk.io) and sign in using your SSO-linked email address.

[claude]

Minor phrasing nit: "instead of SSO" is slightly awkward. Consider:

Suggested change

	If you accidentally created your Trunk account with a personal email instead of your corporate email (for example, by signing in with GitHub OAuth instead of SSO), contact [support@trunk.io](mailto:support@trunk.io) to update your account email.
	If you accidentally created your Trunk account with a personal email instead of your corporate email (for example, by signing in with GitHub OAuth instead of using SSO), contact [support@trunk.io](mailto:support@trunk.io) to update your account email.

[claude]

This answer only addresses users who previously signed in via OAuth, but doesn't clarify what happens to SSO-only users during an outage (they may be completely locked out). Consider expanding:

Suggested change

	If your identity provider experiences an outage, users who previously signed in via OAuth will still be able to access Trunk using their OAuth credentials. Contact [support@trunk.io](mailto:support@trunk.io) if you need emergency access.
	**What happens if SSO goes down?**\
	If your identity provider experiences an outage, users who previously signed in via OAuth will still be able to access Trunk using their OAuth credentials. Users who are SSO-only may be unable to sign in until the outage is resolved. Contact [support@trunk.io](mailto:support@trunk.io) if you need emergency access.

[github-actions]

/trunk merge

[github-actions]

Auto-approved: Claude code review passed.

[trunk-staging-io]

🚫 This pull request was closed by @samgutentag, so it was removed from the merge queue. See more details here.

[samgutentag]

Closing — generated by an earlier version of the docs pipeline. Will re-run with updated skill.