docs: document RBAC support for SSO authentication

.vale/styles/FernStyles/Headings.yml

@@ -61,6 +61,7 @@ exceptions:
   - TLS
   - JWT
   - OAuth2
+  - SSO
   - API
   - CircleCI
   - GitLab CI

fern/products/docs/pages/authentication/overview.mdx

@@ -24,7 +24,7 @@ Fern offers four ways to authenticate users on your documentation site:
 ## Which option should I use?
 
 - **[Password protection](/learn/docs/authentication/setup/password-protection)** — You need quick gating with a shared password (no per-user accounts). Supports multiple passwords mapped to roles for [role-based access control](/learn/docs/authentication/features/rbac).
-- **[SSO](/learn/docs/authentication/setup/sso)** — Your team should log in with corporate credentials (Okta, Google Workspace, etc.) for internal docs or wikis.
+- **[SSO](/learn/docs/authentication/setup/sso)** — Your team should log in with corporate credentials (Okta, Google Workspace, etc.) for internal docs or wikis. Supports [role-based access control](/learn/docs/authentication/features/rbac) when your identity provider includes roles on the token.
 - **[JWT](/learn/docs/authentication/setup/jwt)** — You want to integrate with your existing login system and control the entire auth flow yourself. Supports [role-based access control](/learn/docs/authentication/features/rbac) and [API key injection](/learn/docs/authentication/features/api-key-injection).
 - **[OAuth](/learn/docs/authentication/setup/oauth)** — You want to integrate with your existing login system but have Fern manage the auth flow via your OAuth provider. Supports [role-based access control](/learn/docs/authentication/features/rbac) and [API key injection](/learn/docs/authentication/features/api-key-injection).
 

fern/products/docs/pages/authentication/rbac.mdx

@@ -5,10 +5,10 @@ description: Restrict pages by role, team, or pricing tier so each audience sees
 ---
 
 <Warning title="Team and Enterprise feature">
-  Password-based RBAC is available on the [Team and Enterprise plans](https://buildwithfern.com/pricing). JWT and OAuth-based RBAC require the [Enterprise plan](https://buildwithfern.com/pricing).
+  Password-based RBAC is available on the [Team and Enterprise plans](https://buildwithfern.com/pricing). SSO, JWT, and OAuth-based RBAC require the [Enterprise plan](https://buildwithfern.com/pricing).
 </Warning>
 
-RBAC gates pages, sections, and other navigation items by role so each audience sees only the content meant for them. It works with [password protection](/learn/docs/authentication/setup/password-protection), [JWT](/learn/docs/authentication/setup/jwt), and [OAuth](/learn/docs/authentication/setup/oauth) authentication.
+RBAC gates pages, sections, and other navigation items by role so each audience sees only the content meant for them. It works with [password protection](/learn/docs/authentication/setup/password-protection), [SSO](/learn/docs/authentication/setup/sso), [JWT](/learn/docs/authentication/setup/jwt), and [OAuth](/learn/docs/authentication/setup/oauth) authentication.
 
 Use it for partner docs, beta features, tiered pricing content, and internal resources. You can combine it with [API key injection](/learn/docs/authentication/features/api-key-injection) when using JWT or OAuth authentication. When RBAC is configured, [Ask Fern](/learn/docs/ai-features/ask-fern/overview) automatically respects these permissions. By default, restricted pages are completely hidden from unauthorized users — if you'd like them to be visible but locked instead, let Fern know during setup.
 
@@ -27,7 +27,7 @@ Restricted pages display a lock icon next to the page title. Hovering over the i
   RBAC is configured in `docs.yml` and managed through the [Fern CLI](/learn/cli-api-reference/cli-reference/overview). If you set up your site using the [guided UI](https://dashboard.buildwithfern.com/get-started), you'll need to work with your Fern configuration files directly instead of through the Fern Dashboard.
 </Info>
 
-To enable RBAC, first set up an authentication method — [password protection](/learn/docs/authentication/setup/password-protection), [JWT](/learn/docs/authentication/setup/jwt), or [OAuth](/learn/docs/authentication/setup/oauth) — then define your roles in `docs.yml`:
+To enable RBAC, first set up an authentication method — [password protection](/learn/docs/authentication/setup/password-protection), [SSO](/learn/docs/authentication/setup/sso), [JWT](/learn/docs/authentication/setup/jwt), or [OAuth](/learn/docs/authentication/setup/oauth) — then define your roles in `docs.yml`:
 
 ```yml docs.yml
 roles:

fern/products/docs/pages/authentication/sso.mdx

@@ -8,7 +8,7 @@ subtitle: Put your docs behind your organization's login
 
 SSO lets your team access your docs through your organization's identity provider using SAML 2.0 or OIDC. Like [RBAC](/learn/docs/authentication/features/rbac) and [API key injection](/learn/docs/authentication/features/api-key-injection), SSO uses the [`fern_token`](/learn/docs/authentication/overview#how-authentication-works) cookie to identify authenticated users. SSO unlocks the [Fern Editor](/learn/docs/writing-content/fern-editor) for browser-based editing and [authenticated preview links](/learn/docs/preview-publish/preview-changes#preview-links).
 
-<Note>SSO provides login-based access control but doesn't support role management or API key injection. For granular access control, use [RBAC](/learn/docs/authentication/features/rbac) instead.</Note>
+<Note>SSO supports [RBAC](/learn/docs/authentication/features/rbac) for role-gated content, but not [API key injection](/learn/docs/authentication/features/api-key-injection). For pre-filled API keys, use [JWT](/learn/docs/authentication/setup/jwt) or [OAuth](/learn/docs/authentication/setup/oauth).</Note>
 
 ## How it works
 
@@ -38,3 +38,28 @@ sequenceDiagram
 ## Setup
 
 Fern supports any SAML 2.0 or OIDC provider (Okta, Google Workspace, Auth0, Azure AD, OneLogin, etc.). [Contact Fern](https://buildwithfern.com/book-demo) or reach out via Slack. Fern will work with your security team to connect to your identity provider.
+
+## Role-based access control
+
+SSO can gate content by role. Fern reads each user's roles from the WorkOS token issued at login, then applies the [`roles`](/learn/docs/authentication/features/rbac#setup) and [`viewers`](/learn/docs/authentication/features/rbac#in-navigation) rules in your `docs.yml`.
+
+Fern's SSO runs on [WorkOS](/learn/docs/getting-started/how-it-works), so roles are assigned through your WorkOS organization. Fern coordinates this setup with you.
+
+<Steps>
+<Step title="Enable Organization Roles in WorkOS">
+Turn on Organization Roles (RBAC) for your organization, then define a role for each audience you gate content for (for example, `admins` or `partners`). Each role's slug is the value Fern reads from the token.
+</Step>
+
+<Step title="Assign roles to users">
+Give each user a role in one of two ways:
+
+- Assign a role directly to a member of the organization.
+- Map your identity provider's SSO or directory groups to WorkOS roles so members inherit a role from their group membership. Group mapping requires directory sync (SCIM).
+</Step>
+
+<Step title="Declare the same roles in `docs.yml`">
+List the WorkOS role slugs under `roles` in `docs.yml`, then gate navigation and page content with `viewers` and the `<If />` component. See [Role-based access control](/learn/docs/authentication/features/rbac) for the full setup.
+</Step>
+</Steps>
+
+Fern reads the organization role by default. To read roles from a different token claim instead (for example, a directory-group claim), tell Fern which claim to parse.

fern/products/docs/pages/changelog/2026-07-20.mdx

@@ -0,0 +1,9 @@
+## SSO now supports role-based access control
+
+<ChangelogTags>security</ChangelogTags>
+
+You can now gate content by role when authenticating with [SSO](/learn/docs/authentication/setup/sso). Fern reads each user's roles from the token your identity provider issues, then applies the `roles` and `viewers` rules in your `docs.yml`. Previously, role-based access control was limited to JWT and OAuth.
+
+To use it, assign roles through your WorkOS organization, either directly or by mapping your SSO/directory groups to roles.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/authentication/setup/sso#role-based-access-control">Read the docs</Button>