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
@@ -6,59 +6,88 @@ 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
+
## Introduction
10
+
11
+
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.
12
+
13
+
### Use cases
14
+
15
+
Role-based access control is helpful for scenarios such as:
16
+
17
+
-**Partner documentation**: Provide exclusive API documentation to integration partners while keeping internal docs private
18
+
-**Beta features**: Share new features with beta users before general release
19
+
-**Internal documentation**: Restrict sensitive documentation to employees only
20
+
-**Tiered access**: Offer different documentation levels based on subscription tiers
21
+
-**Customer-specific content**: Show different documentation based on customer type or plan
22
+
23
+
### How it works
24
+
25
+
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.
26
+
27
+
Below, we walk through each of the steps required to configure RBAC.
28
+
29
+
### Architecture diagram
30
+
31
+
```mermaid
32
+
sequenceDiagram
33
+
participant U as User
34
+
participant F as Fern Docs
35
+
participant R as Redirect URL
36
+
participant A as Auth System
37
+
38
+
U->>F: Visit restricted page
39
+
F->>F: Check fern_token cookie
40
+
41
+
alt Cookie exists
42
+
F->>F: Decode JWT with secret key
43
+
F->>F: Extract roles from JWT
44
+
F->>F: Check if user has required role
45
+
46
+
alt User has required role
47
+
F->>U: Show restricted content
48
+
else User lacks required role
49
+
F->>R: Redirect to login page
50
+
R->>A: Authenticate user
51
+
end
52
+
else No cookie
53
+
F->>R: Redirect to login page
54
+
R->>A: Authenticate user
55
+
end
56
+
57
+
Note over A: User logs in
58
+
59
+
A->>A: Generate JWT with roles
60
+
A->>F: Set fern_token cookie
61
+
F->>F: Validate JWT and roles
62
+
F->>U: Show restricted content
63
+
```
64
+
65
+
## Set up RBAC
11
66
12
67
<Steps>
13
68
### Define all the `roles` in your docs.yml
14
69
15
-
Start by defining all the different roles in your `docs.yml`. You can simply specify this under a `roles` key:
70
+
Start by defining all the different roles in your `docs.yml`. You can specify this under a `roles` key:
16
71
17
72
```yml docs.yml
18
73
roles:
19
-
- everyone # every user is given this role
20
-
- partners
21
-
- beta-users
22
-
- admins
23
-
```
24
-
25
-
<Info>The `everyone` role is a special role. Every user has this role.</Info>
26
-
27
-
### Define viewers on parts of the navigation
28
-
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.
31
-
32
-
```yml docs.yml {7-8,14-16}
33
-
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
42
-
layout:
43
-
- page: Overview
44
-
path: pages/overview.mdx
45
-
- section: Beta Release
46
-
viewers:
47
-
- partners
48
-
- admin
74
+
- everyone # every user is given this role
75
+
- partners
76
+
- beta-users
77
+
- admins
49
78
```
50
79
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.
80
+
<Info>
81
+
The `everyone` role is special. Every user has this role (including unauthenticated users).
82
+
</Info>
53
83
54
84
### Configure authentication via a `fern_token`
55
85
56
86
In this step, we will configure authentication so that Fern can understand what roles a particular user has. Fern expects the user's
57
87
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
88
login page.
59
89
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.
90
+
**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
91
63
92
```json
64
93
{
@@ -68,6 +97,79 @@ with a key called roles.
68
97
}
69
98
```
70
99
71
-
<Note>Please reach out to [email protected] when you are on this step so we can provide you with a secret key.</Note>
100
+
### Contact Fern for setup
101
+
102
+
When you're ready to implement RBAC, **contact [email protected]** to receive your secret key for JWT signing.
103
+
104
+
You'll also need to provide the URL where Fern should send unauthenticated users to log in.
105
+
106
+
<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>
72
107
73
108
</Steps>
109
+
110
+
### Access control within navigation
111
+
112
+
You can designate viewers on the following navigation items:
113
+
- `products`
114
+
- `versions`
115
+
- `tabs`
116
+
- `sections`
117
+
- `pages`
118
+
- `api references`
119
+
- `changelogs`
120
+
121
+
If you don't specify viewers, the content will be visible to _any authenticated user_.
122
+
123
+
```yml docs.yml {6-7, 13-15}
124
+
navigation:
125
+
- tab: Home
126
+
layout:
127
+
- page: Welcome # this page is public
128
+
path: pages/welcome.mdx
129
+
viewer:
130
+
- everyone
131
+
- tab: Documentation
132
+
layout:
133
+
- page: Overview # this page is visible to all logged-in users
134
+
path: pages/overview.mdx
135
+
- section: Beta Release # this section is visible to beta-users and admins
136
+
viewers:
137
+
- beta-users
138
+
- admins
139
+
contents:
140
+
...
141
+
```
142
+
143
+
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.
144
+
145
+
### Access control within MDX pages
146
+
147
+
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.
148
+
149
+
#### Basic usage
150
+
151
+
Use the `<If />` component to conditionally render content based on user roles:
152
+
153
+
```mdx
154
+
<If roles={["beta-users"]}>
155
+
<Callout>
156
+
This callout is only visible to beta users.
157
+
</Callout>
158
+
</If>
159
+
```
160
+
161
+
#### Multiple roles
162
+
163
+
You can specify multiple roles. Content will be visible to users who have **any** of the specified roles:
164
+
165
+
```mdx
166
+
<If roles={["partners", "admins"]}>
167
+
<Callout>
168
+
This content is visible to both partners and admins.
169
+
</Callout>
170
+
</If>
171
+
```
172
+
173
+
<Note>
174
+
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.
0 commit comments