Skip to content

Commit 50e374b

Browse files
ethanpalmethanpalm
authored
Update authentication and personalization docs (#761)
* rename "authentication vs personalization" * Combine information into overview * move files & configure redirects * update page titles and docs.json * add JWT info to auth setup * add OAuth info * add mintlify auth info * add password info * delete individual auth pages; configure redirects * Update sending-data.mdx * remove redundant info * add JWT personalization info * add shared session info * delete individual personalization pages, add redirects * Update partial-authentication-setup.mdx * fix broken links * overview copyedits * setup copyedits * copyedit sending data * clarify hidden page language * add reviewer feedback ✨ * emphasize hidden pages are not restricted
1 parent f5fa291 commit 50e374b

21 files changed

+789
-874
lines changed

‎authentication-personalization/authentication-setup.mdx‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: "Authentication Setup"
3+
description: "Guarantee privacy of your docs by authenticating users"
4+
icon: "file-lock"
5+
---
6+
Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method.
7+
8+
**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options.
9+
10+
<Info>
11+
Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). Please{" "}
12+
<a href="mailto:[email protected]">contact sales</a> for more information.
13+
</Info>
14+
15+
## Configuring authentication
16+
17+
Select the handshake method that you want to configure.
18+
19+
<Tabs>
20+
<Tab title="JWT">
21+
### Prerequisites
22+
23+
* An authentication system that can generate and sign JWTs.
24+
* A backend service that can create redirect URLs.
25+
26+
### Implementation
27+
28+
<Steps>
29+
<Step title="Generate a private key.">
30+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
31+
2. Select **Full Authentication** or **Partial Authentication**.
32+
3. Select **JWT**.
33+
4. Enter the URL of your existing login flow and select **Save changes**.
34+
5. Select **Generate new key**.
35+
6. Store your key securely where it can be accessed by your backend.
36+
</Step>
37+
<Step title="Integrate Mintlify authentication into your login flow.">
38+
Modify your existing login flow to include these steps after user authentication:
39+
40+
* Create a JWT containing the authenticated user's info in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
41+
* Sign the JWT with your secret key, using the EdDSA algorithm.
42+
* Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash.
43+
</Step>
44+
</Steps>
45+
46+
### Example
47+
48+
Your documentation is hosted at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don't have a dashboard).
49+
50+
Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication.
51+
52+
After verifying user credentials:
53+
* Generate a JWT with user data in Mintlify's format.
54+
* Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`.
55+
56+
<CodeGroup>
57+
```ts TypeScript
58+
import * as jose from 'jose';
59+
import { Request, Response } from 'express';
60+
61+
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
62+
63+
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
64+
65+
export async function handleRequest(req: Request, res: Response) {
66+
const user = {
67+
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
68+
groups: res.locals.user.groups,
69+
content: {
70+
firstName: res.locals.user.firstName,
71+
lastName: res.locals.user.lastName,
72+
},
73+
};
74+
75+
const jwt = await new jose.SignJWT(user)
76+
.setProtectedHeader({ alg: 'EdDSA' })
77+
.setExpirationTime('10 s') // 10 second JWT expiration
78+
.sign(signingKey);
79+
80+
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
81+
}
82+
```
83+
84+
```python Python
85+
import jwt # pyjwt
86+
import os
87+
88+
from datetime import datetime, timedelta
89+
from fastapi.responses import RedirectResponse
90+
91+
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
92+
93+
@router.get('/auth')
94+
async def return_mintlify_auth_status(current_user):
95+
jwt_token = jwt.encode(
96+
payload={
97+
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
98+
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
99+
'groups': ['admin'] if current_user.is_admin else [],
100+
'content': {
101+
'firstName': current_user.first_name,
102+
'lastName': current_user.last_name,
103+
},
104+
},
105+
key=private_key,
106+
algorithm='EdDSA'
107+
)
108+
109+
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
110+
```
111+
</CodeGroup>
112+
113+
### Redirecting unauthenticated users
114+
115+
When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:
116+
117+
1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`.
118+
2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`.
119+
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
120+
4. User lands in their original destination.
121+
</Tab>
122+
<Tab title="OAuth 2.0">
123+
### Prerequisites
124+
125+
* An OAuth server that supports the Authorization Code Flow.
126+
* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).
127+
128+
### Implementation
129+
130+
<Steps>
131+
<Step title="Configure your OAuth settings.">
132+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
133+
2. Select **Full Authentication** or **Partial Authentication**.
134+
3. Select **OAuth** and configure these fields:
135+
* **Authorization URL**: Your OAuth endpoint.
136+
* **Client ID**: Your OAuth 2.0 client identifier.
137+
* **Client Secret**: Your OAuth 2.0 client secret.
138+
* **Scopes**: Permissions to request. Use multiple scopes if you need different access levels.
139+
* **Token URL**: Your OAuth token exchange endpoint.
140+
* **Info API URL** (optional): Endpoint to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty.
141+
4. Select **Save changes**.
142+
</Step>
143+
<Step title="Configure your OAuth server.">
144+
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
145+
2. Add the redirect URL as an authorized redirect URL for your OAuth server.
146+
</Step>
147+
<Step title="Create your user info endpoint (optional).">
148+
To enable personalization features, create an API endpoint that:
149+
* Accepts OAuth access tokens for authentication.
150+
* Returns user data in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
151+
152+
Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
153+
</Step>
154+
</Steps>
155+
156+
### Example
157+
158+
Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow.
159+
160+
**Configure your OAuth server details** in your dashboard:
161+
- **Authorization URL**: `https://auth.foo.com/authorization`
162+
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
163+
- **Scopes**: `['docs-user-info']`
164+
- **Token URL**: `https://auth.foo.com/exchange`
165+
- **Info API URL**: `https://api.foo.com/docs/user-info`
166+
167+
**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope, and returns:
168+
169+
```json
170+
{
171+
"content": {
172+
"firstName": "Jane",
173+
"lastName": "Doe"
174+
},
175+
"groups": ["engineering", "admin"]
176+
}
177+
```
178+
179+
**Configure your OAuth server to allow redirects** to your callback URL.
180+
</Tab>
181+
<Tab title="Mintlify Dashboard">
182+
### Prerequisites
183+
184+
* Your documentation users are also your documentation editors.
185+
186+
### Implementation
187+
188+
<Steps>
189+
<Step title="Enable Mintlify dashboard authentication.">
190+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
191+
2. Select **Full Authentication** or **Partial Authentication**.
192+
3. Select **Mintlify Auth**.
193+
4. Select **Enable Mintlify Auth**.
194+
</Step>
195+
<Step title="Add authorized users.">
196+
1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members).
197+
2. Add each person who should have access to your documentation.
198+
3. Assign appropriate roles based on their editing permissions.
199+
</Step>
200+
</Steps>
201+
202+
### Example
203+
204+
Your documentation is hosted at `docs.foo.com` and your team uses the dashboard to edit your docs. You want to restrict access to team members only.
205+
206+
**Enable Mintlify authentication** in your dashboard settings.
207+
208+
**Verify team access** by checking that all team members are added to your organization.
209+
</Tab>
210+
<Tab title="Password">
211+
<Info>
212+
Password authentication provides access control only and does **not** support content personalization.
213+
</Info>
214+
215+
### Prerequisites
216+
217+
* Your security requirements allow sharing passwords among users.
218+
219+
### Implementation
220+
221+
<Steps>
222+
<Step title="Create a password.">
223+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
224+
2. Select **Full Authentication** or **Partial Authentication**.
225+
3. Select **Password**.
226+
4. Enter a secure password.
227+
5. Select **Save changes**.
228+
</Step>
229+
<Step title="Distribute access.">
230+
Securely share the password and documentation URL with authorized users.
231+
</Step>
232+
</Steps>
233+
234+
## Example
235+
236+
Your documentation is hosted at `docs.foo.com` and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.
237+
238+
**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!
239+
</Tab>
240+
</Tabs>

‎authentication-personalization/overview.mdx‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "Overview"
3+
description: "Control who sees your documentation and customize their experience"
4+
icon: "badge-info"
5+
---
6+
<Info>
7+
Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). Please{" "}
8+
<a href="mailto:[email protected]">contact sales</a> for more information.
9+
</Info>
10+
11+
There are three approaches to manage access and customize your documentation based on user information.
12+
13+
* **Authentication**: Complete privacy protection for all content with full content customization.
14+
* **Partial authentication**: Page-by-page access control with full content customization.
15+
* **Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible.
16+
17+
**Choose authentication** if you need complete security and privacy for all your documentation, including pages, images, search results, and AI assistant features.
18+
19+
**Choose partial authentication** if you want some pages to be public and others private.
20+
21+
**Choose personalization** if you want to customize content based on user information and your documentation can be publicly accessible.
22+
23+
## Handshake methods
24+
25+
Authentication and personalization offer multiple handshake methods for controlling access to your content.
26+
27+
### Available for all methods
28+
29+
**JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow.
30+
* Pros of JWT:
31+
* Reduced risk of API endpoint abuse.
32+
* No CORS configuration.
33+
* No restrictions on API URLs.
34+
* Cons of JWT:
35+
* Must be compatible with your existing login flow.
36+
* Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
37+
* When you refresh user data, users must log into your docs again. If your users' data changes frequently, they must log in frequently or risk having stale data in your docs.
38+
39+
**OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers.
40+
* Pros of OAuth 2.0:
41+
* Heightened security standard.
42+
* No restrictions on API URLs.
43+
* Cons of OAuth 2.0:
44+
* Requires significant work if setting up an OAuth server for the first time.
45+
* Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
46+
47+
### Available for authentication and partial authentication
48+
49+
**Mintlify dashboard**: Allow all of your dashboard users to access your docs.
50+
* Pros of Mintlify dashboard:
51+
* No configuration required.
52+
* Enables private preview deployments, restricting access to authenticated users only.
53+
* Cons of Mintlify dashboard:
54+
* Requires all users of your docs to have an account in your Mintlify dashboard.
55+
56+
**Password**: Shared access with a single global password. Used for access control only. Does not allow for personalization.
57+
* Pros of password:
58+
* Simple setup with no configuration required to add new users, just share the password.
59+
* Cons of password:
60+
* Lose personalization features since there is no way to differentiate users with the same password.
61+
* Must change the password to revoke access.
62+
63+
### Available for personalization
64+
65+
**Shared session**: Use the same session token as your dashboard to personalize content.
66+
* Pros of shared session:
67+
* Users that are logged into your dashboard are automatically logged into your docs.
68+
* User sessions are persistent so you can refresh data without requiring a new login.
69+
* Minimal setup.
70+
* Cons of shared session:
71+
* Your docs will make a request to your backend.
72+
* You must have a dashboard that uses session authentication.
73+
* CORS configuration is generally required.
74+
75+
## Content customization
76+
77+
All three methods allow you to customize content with these features.
78+
79+
### Dynamic `MDX` content
80+
81+
Display dynamic content based on user information like name, plan, or organization.
82+
83+
The `user` variable contains information sent to your docs from logged in users. See [Sending data](/authentication-personalization/sending-data) for more information.
84+
85+
**Example**: Hello, {user.name ?? 'reader'}!
86+
87+
```jsx
88+
Hello, {user.name ?? 'reader'}!
89+
```
90+
91+
This feature is more powerful when you pair it with custom data about your users. For example, you can give different instructions based on a user's plan.
92+
93+
**Example**: Authentication is an enterprise feature. {
94+
user.org === undefined
95+
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
96+
: user.org.plan !== 'enterprise'
97+
? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
98+
: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
99+
}
100+
101+
```jsx
102+
Authentication is an enterprise feature. {
103+
user.org === undefined
104+
? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
105+
: user.org.plan !== 'enterprise'
106+
? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
107+
: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
108+
}
109+
```
110+
111+
<Note>
112+
The information in `user` is only available for logged in users. For
113+
logged out users, the value of `user` will be `{}`. To prevent the page from
114+
crashing for logged out users, always use optional chaining on your `user`
115+
fields. For example, `{user.org?.plan}`.
116+
</Note>
117+
118+
### API key prefilling
119+
120+
Automatically populate API playground fields with user-specific values by returning matching field names in your user data. The field names in your user data must exactly match the names in the API playground for automatic prefilling to work.
121+
122+
### Page visibility
123+
124+
Restrict which pages are visible to your users by adding `groups` fields to your pages' frontmatter. By default, every page is visible to every user.
125+
126+
Users will only see pages for `groups` that they are in.
127+
128+
```md
129+
---
130+
title: "Managing your users"
131+
description: "Adding and removing users from your organization"
132+
groups: ["admin"]
133+
---
134+
```

0 commit comments

Comments
 (0)