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
Copy file name to clipboardExpand all lines: fern/products/docs/pages/api-references/autopopulate-api-key.mdx
+51-3Lines changed: 51 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,17 @@ Fern can integrate with your authentication flow, allowing users to login and ha
13
13
14
14
With this feature, you can **create new users of your API** directly from within your documentation.
15
15
16
-
## How it works
16
+
## Integrating with your auth flow
17
+
18
+
API key injection can work in two different ways depending on your company's authentication setup: **JWT or OAuth**.
19
+
20
+
***JWT Flow:** You handle the entire auth flow and just give Fern a JWT cookie
21
+
***OAuth Flow:** You give Fern access, and Fern directly initiates the OAuth handshake process
22
+
23
+
<AccordionGrouptoc={true}>
24
+
<Accordiontitle="JWT"toc={true}>
25
+
26
+
### How the JWT flow works
17
27
18
28
To enable this feature, you need to configure authentication so that Fern can securely retrieve API keys for your users. The process works as follows:
19
29
@@ -77,11 +87,49 @@ The JWT should have a structure similar to:
77
87
78
88
</CodeBlocks>
79
89
80
-
## Setting up auto-populated API keys
90
+
#### Architecture diagram
91
+
92
+
<Markdownsrc="/snippets/jwt-auth-diagram.mdx"/>
93
+
94
+
#### Setting up auto-populated API keys
81
95
82
96
-[ ] Reach out to Fern to get your secret key
83
-
-[ ] Send Fern the URL of your authentication page (this is where users will be redirected to after clicking the "Login" button in the API Explorer)
97
+
-[ ] Send Fern the URL of your authentication page. This is where users will be redirected to after clicking the "Login" button in the API Explorer.
84
98
-[ ] Add logic to your service to set the `fern_token` cookie when a user logs in
85
99
86
100
<Tip>For an example of how to set up the `fern_token` cookie, see our demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts).</Tip>
87
101
102
+
</Accordion>
103
+
<Accordiontitle="OAuth"toc={true}>
104
+
105
+
### How the OAuth flow works
106
+
107
+
To enable this feature, you need to configure OAuth authentication so that Fern can securely retrieve API keys for your users through your OAuth provider. Here's how the process works:
108
+
109
+
1. When a user clicks the "Login" button in the API Explorer, Fern initiates an OAuth flow by making a request to your authorization endpoint.
110
+
1. The user is redirected to your OAuth provider's login page where they authenticate using your existing auth system.
111
+
1. After successful authentication, your OAuth provider redirects back to Fern with an authorization code, which Fern exchanges for an access token at your token endpoint.
112
+
1. Fern sets a `fern_token` cookie containing the user's authentication credentials and automatically populates their API key in the API Explorer.
113
+
114
+
#### Architecture diagram
115
+
116
+
<Markdownsrc="/snippets/oauth-diagram.mdx"/>
117
+
118
+
#### Setting up auto-populated API keys
119
+
120
+
To enable API key injection, you'll need to:
121
+
-[ ] Set up an authenticated account for Fern so Fern can authorize users on your behalf.
122
+
-[ ] Configure your OAuth application to return user API keys when Fern requests them
123
+
124
+
Then, you'll need to send Fern the following items:
125
+
- The client ID and client secret for Fern's authenticated account
126
+
- The URL of your authentication endpoint. This is where users will be redirected to after clicking the "Login" button in the API Explorer.
127
+
- The URL of your token endpoint. This is where Fern exchanges codes for tokens.
description: Understand the different authentication options Fern offers
4
+
---
5
+
6
+
Fern offers two methods of authentication, Single Sign-On (SSO) and Role-Based Access Control (RBAC).
7
+
8
+
**For most situations, we recommend using RBAC** for granular access control over your documentation. RBAC works well for sites with multiple audiences (internal teams, partners, customers) and supports API key injection to auto-populate code examples.
9
+
10
+
API key injection can be set up using either JWT or OAuth, depending on your existing authentication system.
11
+
12
+
**SSO is simpler** but only provides basic login functionality - it doesn't support RBAC or API key injection. SSO works well for internal-only documentation where everyone should see the same content.
Copy file name to clipboardExpand all lines: fern/products/docs/pages/authentication/rbac.mdx
+23-43Lines changed: 23 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,43 +24,6 @@ Role-based access control is helpful for scenarios such as:
24
24
25
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
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->>U: User is shown a 404 page
50
-
end
51
-
else No cookie
52
-
F->>R: Redirect to login page
53
-
R->>A: Authenticate user
54
-
end
55
-
56
-
Note over A: User logs in
57
-
58
-
A->>A: Generate JWT with roles
59
-
A->>F: Set fern_token cookie
60
-
F->>F: Validate JWT and roles
61
-
F->>U: Show restricted content
62
-
```
63
-
64
27
## Set up RBAC
65
28
66
29
<Steps>
@@ -82,10 +45,16 @@ The `everyone` role is special. Every user has this role (including unauthentica
82
45
83
46
### Configure authentication via a `fern_token`
84
47
85
-
In this step, we will configure authentication so that Fern can understand what roles a particular user has. Fern expects the user's
86
-
browser session to have a cookie called `fern_token`. If the cookie is not present, the user will be redirected to your company's
87
-
login page.
48
+
In this step, we will configure authentication so that Fern can understand what roles a particular user has.
49
+
50
+
Fern expects the user's browser session to have a cookie called `fern_token`. If
51
+
the cookie is not present, the user will be redirected to your company's login
52
+
page.
88
53
54
+
Below, we walk through each of the steps required to configure RBAC with either JWT or OAuth.
55
+
56
+
<AccordionGroup>
57
+
<Accordion title="JWT">
89
58
**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`.
90
59
91
60
```json
@@ -96,11 +65,22 @@ login page.
96
65
}
97
66
```
98
67
99
-
### Contact Fern for setup
68
+
<Markdown src="/snippets/jwt-auth-diagram.mdx"/>
100
69
101
-
When you're ready to implement RBAC, **contact [email protected]** to receive your secret key for JWT signing.
70
+
</Accordion>
71
+
<Accordion title="OAuth">
72
+
73
+
Fern initiates an OAuth flow when the user needs authentication, redirecting them to your authentication endpoint. Fern creates and sets the `fern-token` cookie after completing this flow.
74
+
You are responsible for configuring your OAuth endpoints to return user role information.
75
+
76
+
<Markdown src="/snippets/oauth-diagram.mdx"/>
77
+
78
+
</Accordion>
79
+
</AccordionGroup>
80
+
81
+
### Contact Fern for setup
102
82
103
-
You'll also need to provide the URL where Fern should send unauthenticated users to log in.
<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>
subtitle: Enterprise authentication for secure access to your Fern dashboard
3
+
subtitle: Enterprise authentication for secure access to your docs
4
4
---
5
5
6
-
Fern’s Single Sign-On (SSO) is an enterprise feature that lets your team securely access the Fern dashboard at `dashboard.buildwithfern.com` using your organization’s identity provider. This is designed for internal contributors, such as technical writers, product managers, or engineers, who need access to want to contribute to your documentation, view web analytics, or manage organizational settings.
6
+
Fern’s Single Sign-On (SSO) is an enterprise feature that lets your team securely access your docs through your organization’s identity provider.
7
+
8
+
<Note>SSO does not support Role-Based Access Control or API Key Injection.</Note>
7
9
8
10
## What SSO unlocks
9
11
10
-
When SSO is enabled for your organization, authenticated users of Fern gain access to:
12
+
When SSO is enabled for your organization, authenticated users of Fern can:
11
13
12
-
-**Manage Users of your Organization**: Add teammates and configure settings for your organization
13
-
-**Access Ask Fern Analytics**: See AI-assisted search usage and browse verbatim user questions
14
-
-**View Web Analytics**: Track key site metrics, like page views and unique visitors **(coming soon)**
15
14
-**Use the Visual Editor**: Make edits to your docs from the browser
15
+
-**Send Authenticated Preview Links** Only authenticated users can view [preview links](docs/preview-publish/previewing-changes-locally)
16
16
17
17
## How it works
18
18
19
-
Fern's SSO integration allows your team to use their existing corporate credentials to access the Fern dashboard. Instead of managing separate Fern accounts, users authenticate through your organization's identity provider and are automatically granted appropriate access to your Fern resources.
19
+
Fern's SSO integration allows your team to use their existing corporate credentials to access your Fern Docs site.
20
+
21
+
### Architecture diagram
22
+
23
+
```mermaid
24
+
sequenceDiagram
25
+
participant U as User
26
+
participant F as Fern Docs
27
+
participant I as Identity Provider
28
+
29
+
U->>F: Click "Login"
30
+
F->>I: Redirect to SSO login
31
+
32
+
Note over I: User authenticates with corporate credentials
33
+
34
+
I->>I: Validate user credentials
35
+
I->>F: Redirect back with fern_token
36
+
F->>F: Grant access to organizational features
37
+
F->>U: Show docs site
38
+
```
20
39
21
40
## Supported identity providers
22
41
@@ -25,6 +44,7 @@ Fern supports SSO integration with any identity provider that implements industr
25
44
-**SAML 2.0**: Compatible with providers like Okta, OneLogin, Azure AD, and others
26
45
-**OIDC (OpenID Connect)**: Works with Google Workspace, Auth0, and other OIDC-compliant providers
27
46
28
-
<Note>
29
-
SSO is available as part of the Enterprise plan. Reach out via Slack or [contact our team](https://buildwithfern.com/contact) to begin the SSO setup process.
30
-
</Note>
47
+
## Setting up SSO
48
+
49
+
SSO is available as part of the Enterprise plan. Reach out via Slack or [contact our team](https://buildwithfern.com/contact) to begin the SSO setup process. Fern will work with one of your security administrators to connect to your identity provider.
0 commit comments