From 7e339d7668e921c6ab91da9f8f94da59bdeea4ff Mon Sep 17 00:00:00 2001 From: "sandeep.dinesh" Date: Mon, 20 Jul 2026 15:05:24 +0000 Subject: [PATCH 1/3] docs: document RBAC support for SSO authentication Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/authentication/overview.mdx | 2 +- fern/products/docs/pages/authentication/rbac.mdx | 6 +++--- fern/products/docs/pages/authentication/sso.mdx | 10 +++++++++- fern/products/docs/pages/changelog/2026-07-20.mdx | 9 +++++++++ 4 files changed, 22 insertions(+), 5 deletions(-) create mode 100644 fern/products/docs/pages/changelog/2026-07-20.mdx diff --git a/fern/products/docs/pages/authentication/overview.mdx b/fern/products/docs/pages/authentication/overview.mdx index 60335d067d..b1a41ca1d3 100644 --- a/fern/products/docs/pages/authentication/overview.mdx +++ b/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). diff --git a/fern/products/docs/pages/authentication/rbac.mdx b/fern/products/docs/pages/authentication/rbac.mdx index c58e5902e0..19a265100b 100644 --- a/fern/products/docs/pages/authentication/rbac.mdx +++ b/fern/products/docs/pages/authentication/rbac.mdx @@ -5,10 +5,10 @@ description: Restrict pages by role, team, or pricing tier so each audience sees --- - 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). -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. -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: diff --git a/fern/products/docs/pages/authentication/sso.mdx b/fern/products/docs/pages/authentication/sso.mdx index 9f662973e0..340e48976d 100644 --- a/fern/products/docs/pages/authentication/sso.mdx +++ b/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). -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. +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). ## How it works @@ -38,3 +38,11 @@ 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 token your identity provider issues, then applies the [`roles`](/learn/docs/authentication/features/rbac#setup) and [`viewers`](/learn/docs/authentication/features/rbac#in-navigation) rules in your `docs.yml`. + +The identity provider must include the user's roles on the token. Enable organization roles in your provider, then either assign roles to users directly or map your SSO/directory groups to those roles. Fern uses the organization role by default; to read roles from a custom token claim instead, tell Fern which claim to parse. + +Once roles reach the token, define them in `docs.yml` and gate navigation and page content as described in [Role-based access control](/learn/docs/authentication/features/rbac). Contact Fern to enable roles on your SSO connection. diff --git a/fern/products/docs/pages/changelog/2026-07-20.mdx b/fern/products/docs/pages/changelog/2026-07-20.mdx new file mode 100644 index 0000000000..91b3708c10 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-07-20.mdx @@ -0,0 +1,9 @@ +## SSO now supports role-based access control + +security + +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, include the user's roles on the SSO token by enabling organization roles in your provider and assigning roles directly or mapping SSO/directory groups to them. + + From 38b9914199bd5dec0a8f75b83936c2b56e1486d0 Mon Sep 17 00:00:00 2001 From: "sandeep.dinesh" Date: Mon, 20 Jul 2026 15:10:15 +0000 Subject: [PATCH 2/3] docs: add concrete steps for assigning SSO roles via WorkOS Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../docs/pages/authentication/sso.mdx | 23 ++++++++++++++++--- .../docs/pages/changelog/2026-07-20.mdx | 2 +- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/fern/products/docs/pages/authentication/sso.mdx b/fern/products/docs/pages/authentication/sso.mdx index 340e48976d..ae5c36c106 100644 --- a/fern/products/docs/pages/authentication/sso.mdx +++ b/fern/products/docs/pages/authentication/sso.mdx @@ -41,8 +41,25 @@ Fern supports any SAML 2.0 or OIDC provider (Okta, Google Workspace, Auth0, Azur ## Role-based access control -SSO can gate content by role. Fern reads each user's roles from the token your identity provider issues, then applies the [`roles`](/learn/docs/authentication/features/rbac#setup) and [`viewers`](/learn/docs/authentication/features/rbac#in-navigation) rules in your `docs.yml`. +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`. -The identity provider must include the user's roles on the token. Enable organization roles in your provider, then either assign roles to users directly or map your SSO/directory groups to those roles. Fern uses the organization role by default; to read roles from a custom token claim instead, tell Fern which claim to parse. +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. -Once roles reach the token, define them in `docs.yml` and gate navigation and page content as described in [Role-based access control](/learn/docs/authentication/features/rbac). Contact Fern to enable roles on your SSO connection. + + +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. + + + +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). + + + +List the WorkOS role slugs under `roles` in `docs.yml`, then gate navigation and page content with `viewers` and the `` component. See [Role-based access control](/learn/docs/authentication/features/rbac) for the full setup. + + + +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. diff --git a/fern/products/docs/pages/changelog/2026-07-20.mdx b/fern/products/docs/pages/changelog/2026-07-20.mdx index 91b3708c10..a3a05d1873 100644 --- a/fern/products/docs/pages/changelog/2026-07-20.mdx +++ b/fern/products/docs/pages/changelog/2026-07-20.mdx @@ -4,6 +4,6 @@ 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, include the user's roles on the SSO token by enabling organization roles in your provider and assigning roles directly or mapping SSO/directory groups to them. +To use it, assign roles through your WorkOS organization, either directly or by mapping your SSO/directory groups to roles. From 4d825b2de6598c6245f763a690ce7dd59e05d9f0 Mon Sep 17 00:00:00 2001 From: "sandeep.dinesh" Date: Mon, 20 Jul 2026 15:13:29 +0000 Subject: [PATCH 3/3] chore: add SSO to Vale heading acronym exceptions Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .vale/styles/FernStyles/Headings.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 904966d046..bbbb4a25b5 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -61,6 +61,7 @@ exceptions: - TLS - JWT - OAuth2 + - SSO - API - CircleCI - GitLab CI