You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
subtitle: Control access to specific content within your pages using RBAC
4
+
---
5
+
6
+
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.
7
+
8
+
## Basic usage
9
+
10
+
Use the `<If>` component to conditionally render content based on user roles:
11
+
12
+
```mdx
13
+
<Ifroles={["beta-users"]}>
14
+
<Callout>
15
+
This callout is only visible to beta users.
16
+
</Callout>
17
+
</If>
18
+
```
19
+
20
+
## Multiple roles
21
+
22
+
You can specify multiple roles. Content will be visible to users who have **any** of the specified roles:
23
+
24
+
```mdx
25
+
<Ifroles={["partners", "admins"]}>
26
+
<Callout>
27
+
This content is visible to both partners and admins.
28
+
</Callout>
29
+
</If>
30
+
```
31
+
32
+
<Note>
33
+
The `<If>` 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.
Copy file name to clipboardExpand all lines: fern/products/docs/pages/authentication/rbac.mdx
+59-29Lines changed: 59 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,59 +6,83 @@ description: Learn how to restrict access to your documentation using role-based
6
6
7
7
<Note>RBAC is part of the pro plan.</Note>
8
8
9
-
Fern allows you to restrict parts of your navigation to individuals with specific roles. Below, we walk through each of the steps
10
-
required to configure RBAC.
9
+
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.
10
+
11
+
## Use cases
12
+
13
+
Role-based access control is helpful for scenarios such as:
14
+
15
+
-**Partner documentation**: Provide exclusive API documentation to integration partners while keeping internal docs private
16
+
-**Beta features**: Share new features with beta users before general release
17
+
-**Internal documentation**: Restrict sensitive documentation to employees only
18
+
-**Tiered access**: Offer different documentation levels based on subscription tiers
19
+
-**Customer-specific content**: Show different documentation based on customer type or plan
20
+
21
+
## How it works
22
+
23
+
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.
24
+
25
+
Below, we walk through each of the steps required to configure RBAC.
11
26
12
27
<Steps>
13
28
### Define all the `roles` in your docs.yml
14
29
15
-
Start by defining all the different roles in your `docs.yml`. You can simply specify this under a `roles` key:
30
+
Start by defining all the different roles in your `docs.yml`. You can specify this under a `roles` key:
16
31
17
32
```yml docs.yml
18
33
roles:
19
-
- everyone # every user is given this role
20
-
- partners
21
-
- beta-users
22
-
- admins
34
+
- everyone # every user is given this role
35
+
- partners
36
+
- beta-users
37
+
- admins
23
38
```
24
39
25
-
<Info>The `everyone` role is a special role. Every user has this role.</Info>
40
+
<Info>
41
+
The `everyone` role is special. Every user has this role (including unauthenticated users).
42
+
</Info>
26
43
27
44
### Define viewers on parts of the navigation
28
45
29
-
Every navigation item (`sections`, `pages`, `api references`) can have a set of designated viewers. If you don't
30
-
specify viewers, then it defaults to `everyone` and the page is public.
46
+
You can designate viewers on the following navigation items:
47
+
- `products`
48
+
- `versions`
49
+
- `tabs`
50
+
- `sections`
51
+
- `pages`
52
+
- `api references`
53
+
- `changelogs`
31
54
32
-
```yml docs.yml {7-8,14-16}
55
+
If you don't specify viewers, the content will be visible to _any authenticated user_.
56
+
57
+
```yml docs.yml {6-7, 13-15}
33
58
navigation:
34
-
- tab: Documentation
35
-
layout:
36
-
- page: Overview
37
-
path: pages/overview.mdx
38
-
- section: Beta Release
39
-
viewers:
40
-
- beta-users
41
-
- tab: API Reference
59
+
- tab: Home
60
+
layout:
61
+
- page: Welcome # this page is public
62
+
path: pages/welcome.mdx
63
+
viewer:
64
+
- everyone
65
+
- tab: Documentation
42
66
layout:
43
-
- page: Overview
44
-
path: pages/overview.mdx
45
-
- section: Beta Release
67
+
- page: Overview # this page is visible to all logged-in users
68
+
path: pages/overview.mdx
69
+
- section: Beta Release # this section is visible to beta-users and admins
46
70
viewers:
47
-
- partners
48
-
- admin
71
+
- beta-users
72
+
- admins
73
+
contents:
74
+
...
49
75
```
50
76
51
-
The viewers are inherited by nested pieces of content. For example, if a section can only be viewed by `admins`, then all its
52
-
pages and nested sections can also only be viewed by admins.
77
+
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.
53
78
54
79
### Configure authentication via a `fern_token`
55
80
56
81
In this step, we will configure authentication so that Fern can understand what roles a particular user has. Fern expects the user's
57
82
browser session to have a cookie called `fern_token`. If the cookie is not present, the user will be redirected to your company's
58
83
login page.
59
84
60
-
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
61
-
with a key called roles.
85
+
**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`.
62
86
63
87
```json
64
88
{
@@ -68,6 +92,12 @@ with a key called roles.
68
92
}
69
93
```
70
94
71
-
<Note>Please reach out to [email protected] when you are on this step so we can provide you with a secret key.</Note>
95
+
### Contact Fern for setup
96
+
97
+
When you're ready to implement RBAC, **contact [email protected]** to receive your secret key for JWT signing.
98
+
99
+
You'll also need to provide the URL where Fern should send unauthenticated users to log in.
100
+
101
+
<Note>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.</Note>
0 commit comments