diff --git a/fern/fern.config.json b/fern/fern.config.json index 03797550e..b66b2bc2e 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "fern", - "version": "0.64.22" -} + "version": "0.65.23" +} \ No newline at end of file diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index ed3c14e13..3b81eead3 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -152,7 +152,7 @@ navigation: contents: - page: SSO path: ./pages/authentication/sso.mdx - - page: RBAC + - page: Role based access control (RBAC) path: ./pages/authentication/rbac.mdx - page: API Key Injection path: ./pages/api-references/autopopulate-api-key.mdx diff --git a/fern/products/docs/pages/authentication/rbac.mdx b/fern/products/docs/pages/authentication/rbac.mdx index 0b05f6cf5..aff022181 100644 --- a/fern/products/docs/pages/authentication/rbac.mdx +++ b/fern/products/docs/pages/authentication/rbac.mdx @@ -6,50 +6,80 @@ description: Learn how to restrict access to your documentation using role-based RBAC is part of the pro plan. -Fern allows you to restrict parts of your navigation to individuals with specific roles. Below, we walk through each of the steps -required to configure RBAC. +## Introduction + +Fern allows you to restrict parts of your navigation to individuals with specific roles. RBAC enables you to create different levels of access for different user types within your documentation. + +### Use cases + +Role-based access control is helpful for scenarios such as: + +- **Partner documentation**: Provide exclusive API documentation to integration partners while keeping internal docs private +- **Beta features**: Share new features with beta users before general release +- **Internal documentation**: Restrict sensitive documentation to employees only +- **Tiered access**: Offer different documentation levels based on subscription tiers +- **Customer-specific content**: Show different documentation based on customer type or plan + +### How it works + +If a user visits content not marked as visible to the `everyone` role, Fern will check for an authentication cookie to indicate what roles that user has. If the user does not have a role matching the viewers of the page, we will redirect them to the URL you provided during setup. + +Below, we walk through each of the steps required to configure RBAC. + +### Architecture diagram + +```mermaid +sequenceDiagram + participant U as User + participant F as Fern Docs + participant R as Redirect URL + participant A as Auth System + + U->>F: Visit restricted page + F->>F: Check fern_token cookie + + alt Cookie exists + F->>F: Decode JWT with secret key + F->>F: Extract roles from JWT + F->>F: Check if user has required role + + alt User has required role + F->>U: Show restricted content + else User lacks required role + F->>R: Redirect to login page + R->>A: Authenticate user + end + else No cookie + F->>R: Redirect to login page + R->>A: Authenticate user + end + + Note over A: User logs in + + A->>A: Generate JWT with roles + A->>F: Set fern_token cookie + F->>F: Validate JWT and roles + F->>U: Show restricted content +``` + +## Set up RBAC ### Define all the `roles` in your docs.yml -Start by defining all the different roles in your `docs.yml`. You can simply specify this under a `roles` key: +Start by defining all the different roles in your `docs.yml`. You can specify this under a `roles` key: ```yml docs.yml roles: - - everyone # every user is given this role - - partners - - beta-users - - admins -``` - -The `everyone` role is a special role. Every user has this role. - -### Define viewers on parts of the navigation - -Every navigation item (`sections`, `pages`, `api references`) can have a set of designated viewers. If you don't -specify viewers, then it defaults to `everyone` and the page is public. - -```yml docs.yml {7-8,14-16} -navigation: - - tab: Documentation - layout: - - page: Overview - path: pages/overview.mdx - - section: Beta Release - viewers: - - beta-users - - tab: API Reference - layout: - - page: Overview - path: pages/overview.mdx - - section: Beta Release - viewers: - - partners - - admin + - everyone # every user is given this role + - partners + - beta-users + - admins ``` -The viewers are inherited by nested pieces of content. For example, if a section can only be viewed by `admins`, then all its -pages and nested sections can also only be viewed by admins. + +The `everyone` role is special. Every user has this role (including unauthenticated users). + ### Configure authentication via a `fern_token` @@ -57,8 +87,7 @@ In this step, we will configure authentication so that Fern can understand what browser session to have a cookie called `fern_token`. If the cookie is not present, the user will be redirected to your company's login page. -Upon login, you must set a JWT for the user using a secret key that we will provide you with. The JWT must have a `fern` claim -with a key called roles. +**You are responsible for creating and setting the `fern_token` cookie in your authentication system.** Upon login, you must set a JWT for the user using a secret key that we will provide. The JWT must have a `fern` claim with a key called `roles`. ```json { @@ -68,6 +97,79 @@ with a key called roles. } ``` -Please reach out to support@buildwithfern.com when you are on this step so we can provide you with a secret key. +### Contact Fern for setup + +When you're ready to implement RBAC, **contact support@buildwithfern.com** to receive your secret key for JWT signing. + +You'll also need to provide the URL where Fern should send unauthenticated users to log in. + +Optional: If you'd like restricted pages to be visible but locked to unauthenticated users (rather than completely hidden), let us know during this step. + +### Access control within navigation + +You can designate viewers on the following navigation items: +- `products` +- `versions` +- `tabs` +- `sections` +- `pages` +- `api references` +- `changelogs` + +If you don't specify viewers, the content will be visible to _any authenticated user_. + +```yml docs.yml {6-7, 13-15} +navigation: + - tab: Home + layout: + - page: Welcome # this page is public + path: pages/welcome.mdx + viewer: + - everyone + - tab: Documentation + layout: + - page: Overview # this page is visible to all logged-in users + path: pages/overview.mdx + - section: Beta Release # this section is visible to beta-users and admins + viewers: + - beta-users + - admins + contents: + ... +``` + +Viewership is inherited. For example, if a section can only be viewed by `admins`, then all its pages and nested sections can also only be viewed by admins. + +### Access control within MDX pages + +You can restrict specific content within your MDX pages to users with certain roles. This allows you to show different content to different user types on the same page. + +#### Basic usage + +Use the `` component to conditionally render content based on user roles: + +```mdx + + + This callout is only visible to beta users. + + +``` + +#### Multiple roles + +You can specify multiple roles. Content will be visible to users who have **any** of the specified roles: + +```mdx + + + This content is visible to both partners and admins. + + +``` + + +The `` component respects the same role inheritance rules as navigation items. If a user has access to a page, they can see all content on that page that matches their roles. +