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 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..ae5c36c106 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,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. + + + +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 new file mode 100644 index 0000000000..a3a05d1873 --- /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, assign roles through your WorkOS organization, either directly or by mapping your SSO/directory groups to roles. + +