Skip to content

Commit 8acdd6b

Browse files
ethanpalmethanpalm
committed
reorder auth methods
1 parent 940e3e6 commit 8acdd6b

File tree

1 file changed

+115
-115
lines changed

1 file changed

+115
-115
lines changed

‎authentication-personalization/authentication-setup.mdx‎

Lines changed: 115 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -19,107 +19,64 @@ Authentication requires users to log in before accessing your documentation. Thi
1919
Select the handshake method that you want to configure.
2020

2121
<Tabs>
22-
<Tab title="JWT">
22+
<Tab title="Password">
23+
<Info>
24+
Password authentication provides access control only and does **not** support content personalization.
25+
</Info>
26+
2327
### Prerequisites
2428

25-
* An authentication system that can generate and sign JWTs.
26-
* A backend service that can create redirect URLs.
29+
* Your security requirements allow sharing passwords among users.
2730

2831
### Implementation
2932

3033
<Steps>
31-
<Step title="Generate a private key.">
34+
<Step title="Create a password.">
3235
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
3336
2. Select **Full Authentication** or **Partial Authentication**.
34-
3. Select **JWT**.
35-
4. Enter the URL of your existing login flow and select **Save changes**.
36-
5. Select **Generate new key**.
37-
6. Store your key securely where it can be accessed by your backend.
37+
3. Select **Password**.
38+
4. Enter a secure password.
39+
5. Select **Save changes**.
3840
</Step>
39-
<Step title="Integrate Mintlify authentication into your login flow.">
40-
Modify your existing login flow to include these steps after user authentication:
41-
42-
* Create a JWT containing the authenticated user's info in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
43-
* Sign the JWT with your secret key, using the EdDSA algorithm.
44-
* Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash.
41+
<Step title="Distribute access.">
42+
Securely share the password and documentation URL with authorized users.
4543
</Step>
4644
</Steps>
4745

48-
### Example
49-
50-
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).
51-
52-
Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication.
53-
54-
After verifying user credentials:
55-
* Generate a JWT with user data in Mintlify's format.
56-
* Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`.
57-
58-
<CodeGroup>
59-
```ts TypeScript
60-
import * as jose from 'jose';
61-
import { Request, Response } from 'express';
62-
63-
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
64-
65-
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
66-
67-
export async function handleRequest(req: Request, res: Response) {
68-
const user = {
69-
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
70-
groups: res.locals.user.groups,
71-
content: {
72-
firstName: res.locals.user.firstName,
73-
lastName: res.locals.user.lastName,
74-
},
75-
};
76-
77-
const jwt = await new jose.SignJWT(user)
78-
.setProtectedHeader({ alg: 'EdDSA' })
79-
.setExpirationTime('10 s') // 10 second JWT expiration
80-
.sign(signingKey);
46+
## Example
8147

82-
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
83-
}
84-
```
48+
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.
8549

86-
```python Python
87-
import jwt # pyjwt
88-
import os
50+
**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!
51+
</Tab>
52+
<Tab title="Mintlify Dashboard">
53+
### Prerequisites
8954

90-
from datetime import datetime, timedelta
91-
from fastapi.responses import RedirectResponse
55+
* Your documentation users are also your documentation editors.
9256

93-
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
57+
### Implementation
9458

95-
@router.get('/auth')
96-
async def return_mintlify_auth_status(current_user):
97-
jwt_token = jwt.encode(
98-
payload={
99-
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
100-
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
101-
'groups': ['admin'] if current_user.is_admin else [],
102-
'content': {
103-
'firstName': current_user.first_name,
104-
'lastName': current_user.last_name,
105-
},
106-
},
107-
key=private_key,
108-
algorithm='EdDSA'
109-
)
59+
<Steps>
60+
<Step title="Enable Mintlify dashboard authentication.">
61+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
62+
2. Select **Full Authentication** or **Partial Authentication**.
63+
3. Select **Mintlify Auth**.
64+
4. Select **Enable Mintlify Auth**.
65+
</Step>
66+
<Step title="Add authorized users.">
67+
1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members).
68+
2. Add each person who should have access to your documentation.
69+
3. Assign appropriate roles based on their editing permissions.
70+
</Step>
71+
</Steps>
11072

111-
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
112-
```
113-
</CodeGroup>
73+
### Example
11474

115-
### Redirecting unauthenticated users
75+
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.
11676

117-
When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:
77+
**Enable Mintlify authentication** in your dashboard settings.
11878

119-
1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`.
120-
2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`.
121-
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
122-
4. User lands in their original destination.
79+
**Verify team access** by checking that all team members are added to your organization.
12380
</Tab>
12481
<Tab title="OAuth 2.0">
12582
### Prerequisites
@@ -180,63 +137,106 @@ Your documentation is hosted at `foo.com/docs` and you have an existing OAuth se
180137

181138
**Configure your OAuth server to allow redirects** to your callback URL.
182139
</Tab>
183-
<Tab title="Mintlify Dashboard">
140+
<Tab title="JWT">
184141
### Prerequisites
185142

186-
* Your documentation users are also your documentation editors.
143+
* An authentication system that can generate and sign JWTs.
144+
* A backend service that can create redirect URLs.
187145

188146
### Implementation
189147

190148
<Steps>
191-
<Step title="Enable Mintlify dashboard authentication.">
149+
<Step title="Generate a private key.">
192150
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
193151
2. Select **Full Authentication** or **Partial Authentication**.
194-
3. Select **Mintlify Auth**.
195-
4. Select **Enable Mintlify Auth**.
152+
3. Select **JWT**.
153+
4. Enter the URL of your existing login flow and select **Save changes**.
154+
5. Select **Generate new key**.
155+
6. Store your key securely where it can be accessed by your backend.
196156
</Step>
197-
<Step title="Add authorized users.">
198-
1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members).
199-
2. Add each person who should have access to your documentation.
200-
3. Assign appropriate roles based on their editing permissions.
157+
<Step title="Integrate Mintlify authentication into your login flow.">
158+
Modify your existing login flow to include these steps after user authentication:
159+
160+
* Create a JWT containing the authenticated user's info in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
161+
* Sign the JWT with your secret key, using the EdDSA algorithm.
162+
* Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash.
201163
</Step>
202164
</Steps>
203165

204166
### Example
205167

206-
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.
168+
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).
207169

208-
**Enable Mintlify authentication** in your dashboard settings.
170+
Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication.
209171

210-
**Verify team access** by checking that all team members are added to your organization.
211-
</Tab>
212-
<Tab title="Password">
213-
<Info>
214-
Password authentication provides access control only and does **not** support content personalization.
215-
</Info>
172+
After verifying user credentials:
173+
* Generate a JWT with user data in Mintlify's format.
174+
* Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`.
216175

217-
### Prerequisites
176+
<CodeGroup>
177+
```ts TypeScript
178+
import * as jose from 'jose';
179+
import { Request, Response } from 'express';
218180

219-
* Your security requirements allow sharing passwords among users.
181+
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
220182

221-
### Implementation
183+
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
222184

223-
<Steps>
224-
<Step title="Create a password.">
225-
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
226-
2. Select **Full Authentication** or **Partial Authentication**.
227-
3. Select **Password**.
228-
4. Enter a secure password.
229-
5. Select **Save changes**.
230-
</Step>
231-
<Step title="Distribute access.">
232-
Securely share the password and documentation URL with authorized users.
233-
</Step>
234-
</Steps>
185+
export async function handleRequest(req: Request, res: Response) {
186+
const user = {
187+
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
188+
groups: res.locals.user.groups,
189+
content: {
190+
firstName: res.locals.user.firstName,
191+
lastName: res.locals.user.lastName,
192+
},
193+
};
235194

236-
## Example
195+
const jwt = await new jose.SignJWT(user)
196+
.setProtectedHeader({ alg: 'EdDSA' })
197+
.setExpirationTime('10 s') // 10 second JWT expiration
198+
.sign(signingKey);
237199

238-
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.
200+
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
201+
}
202+
```
239203

240-
**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!
204+
```python Python
205+
import jwt # pyjwt
206+
import os
207+
208+
from datetime import datetime, timedelta
209+
from fastapi.responses import RedirectResponse
210+
211+
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
212+
213+
@router.get('/auth')
214+
async def return_mintlify_auth_status(current_user):
215+
jwt_token = jwt.encode(
216+
payload={
217+
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
218+
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
219+
'groups': ['admin'] if current_user.is_admin else [],
220+
'content': {
221+
'firstName': current_user.first_name,
222+
'lastName': current_user.last_name,
223+
},
224+
},
225+
key=private_key,
226+
algorithm='EdDSA'
227+
)
228+
229+
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
230+
```
231+
</CodeGroup>
232+
233+
### Redirecting unauthenticated users
234+
235+
When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:
236+
237+
1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`.
238+
2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`.
239+
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
240+
4. User lands in their original destination.
241241
</Tab>
242242
</Tabs>

0 commit comments

Comments
 (0)