Skip to content

Commit b2c83bc

Browse files
rpmccarterrpmccarter
authored
docs: actual auth (#417)
* authentication-related pages * adjust SSO copy * adjust personalization handshake methods * auth jwt and update titles * update authentication handshakes * update paths and separate auth and personalization features * shorten group title * update all references to user auth * update order of auth/personalization docs * add enterprise feature callout * title/description nits * delete comment * update oauth info for authentication * udpate mintlify handshake description * update mintlify dashboard links * fix jwt code * updat eauth method copy
1 parent e90e67b commit b2c83bc

File tree

17 files changed

+447
-62
lines changed

17 files changed

+447
-62
lines changed

‎changelog/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ mode: "wide"
9999

100100
## Filter search based on the current user
101101

102-
When user auth is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
102+
When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
103103

104104
## Custom Prompts for AI Chat
105105

‎mint.json‎

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,35 @@
111111
{
112112
"group": "Configurations",
113113
"pages": [
114+
{
115+
"icon": "user-lock",
116+
"group": "Auth & Personalization",
117+
"pages": [
118+
"settings/authentication-personalization/authentication",
119+
"settings/authentication-personalization/personalization",
120+
"settings/authentication-personalization/authentication-vs-personalization",
121+
{
122+
"group": "Authentication Setup",
123+
"pages": [
124+
"settings/authentication-personalization/authentication-setup/choosing-a-handshake",
125+
"settings/authentication-personalization/authentication-setup/password",
126+
"settings/authentication-personalization/authentication-setup/jwt",
127+
"settings/authentication-personalization/authentication-setup/oauth",
128+
"settings/authentication-personalization/authentication-setup/mintlify"
129+
]
130+
},
131+
{
132+
"group": "Personalization Setup",
133+
"pages": [
134+
"settings/authentication-personalization/personalization-setup/choosing-a-handshake",
135+
"settings/authentication-personalization/personalization-setup/shared-session",
136+
"settings/authentication-personalization/personalization-setup/jwt",
137+
"settings/authentication-personalization/personalization-setup/oauth"
138+
]
139+
},
140+
"settings/authentication-personalization/sending-data"
141+
]
142+
},
114143
"settings/custom-domain",
115144
"settings/seo",
116145
"settings/broken-links",
@@ -156,23 +185,6 @@
156185
"advanced/rest-api/update-status"
157186
]
158187
},
159-
{
160-
"icon": "user-lock",
161-
"group": "User Auth",
162-
"pages": [
163-
"advanced/user-auth/overview",
164-
{
165-
"group": "Authenticating",
166-
"pages": [
167-
"advanced/user-auth/choosing-an-auth-method",
168-
"advanced/user-auth/shared-session",
169-
"advanced/user-auth/jwt",
170-
"advanced/user-auth/oauth"
171-
]
172-
},
173-
"advanced/user-auth/sending-data"
174-
]
175-
},
176188
"settings/authentication"
177189
]
178190
},

‎settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: 'Choosing a Handshake'
3+
description: 'How to decide which Handshake method is right for your docs'
4+
---
5+
6+
<Info>
7+
This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization-setup/choosing-a-handshake).
8+
</Info>
9+
10+
Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods:
11+
12+
1. **Password**: Configure a set of global passwords for your documentation site.
13+
2. **JWT**: Use your own login flow to authenticate your users via a JWT in the URL.
14+
3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the standard Authorization Code flow.
15+
4. **Mintlify Dashboard**: Allow all of your dashboard users to access your docs, zero configuration required.
16+
17+
## Prerequisites
18+
19+
<Tabs>
20+
<Tab title="Password">
21+
22+
- Your security requirements allow for password sharing between documentation readers.
23+
</Tab>
24+
<Tab title="JWT">
25+
26+
- You have some existing login flow.
27+
- You can add a final step in this login flow that creates a JWT and redirects to the docs.
28+
</Tab>
29+
<Tab title="OAuth 2.0">
30+
31+
- You have an existing OAuth server that supports the Authorization Code flow.
32+
- You can create a new API endpoint that can be accessed by the returned OAuth access token.
33+
</Tab>
34+
<Tab title="Mintlify Dashboard">
35+
36+
- Your documentation readers are also your documentation editors.
37+
</Tab>
38+
</Tabs>
39+
40+
## Pros & Cons
41+
42+
<Tabs>
43+
<Tab title="Password">
44+
Pros:
45+
46+
- Super simple setup
47+
- No configuration required for adding new users - just share the password
48+
49+
Cons:
50+
51+
- Difficult to revoke access to your docs without resetting the password
52+
- Lose personalization features, as there is no way to differentiate users with the same password
53+
</Tab>
54+
<Tab title="JWT">
55+
Pros:
56+
57+
- Reduced risk of API endpoint abuse
58+
- Zero CORS configuration
59+
- No restrictions on API URLs
60+
61+
Cons:
62+
63+
- Must be able to hook into your existing login flow
64+
</Tab>
65+
<Tab title="OAuth 2.0">
66+
Pros:
67+
68+
- Heightened security standard
69+
70+
Cons:
71+
72+
- Requires significant work if setting up OAuth server for the first time
73+
- Might be overkill for some applications
74+
</Tab>
75+
<Tab title="Mintlify Dashboard">
76+
Pros:
77+
78+
- Zero-config setup
79+
80+
Cons:
81+
82+
- Requires all docs readers to have an account in your Mintlify dashboard
83+
</Tab>
84+
</Tabs>

‎settings/authentication-personalization/authentication-setup/jwt.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: 'JWT Handshake'
3+
description: 'Use a customized login flow to authenticate users'
4+
---
5+
6+
<Info>
7+
This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
8+
</Info>
9+
10+
If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
11+
12+
## Implementation
13+
14+
<Steps>
15+
<Step title="Generate a private key">
16+
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
17+
</Step>
18+
<Step title="Create a login flow">
19+
Create a login flow that does the following:
20+
- Authenticate the user
21+
- Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format
22+
- Sign the JWT with the secret key, using the EdDSA algorithm
23+
- Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash
24+
</Step>
25+
<Step title="Configure your Authentication settings">
26+
Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings.
27+
</Step>
28+
</Steps>
29+
30+
## Example
31+
32+
I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
33+
to be completely separate from my dashboard (or I don’t have a dashboard at all).
34+
35+
To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
36+
JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
37+
for my users. At the end of this login flow, once I have verified the identity of the user,
38+
I create a JWT containing the user’s custom data according to Mintlify’s specification.
39+
I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
40+
form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
41+
42+
I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
43+
Login URL field.
44+
45+
Here's what the code might look like:
46+
47+
<CodeGroup>
48+
```ts TypeScript
49+
import * as jose from 'jose';
50+
import { Request, Response } from 'express';
51+
52+
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
53+
54+
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
55+
56+
export async function handleRequest(req: Request, res: Response) {
57+
const userInfo = {
58+
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
59+
groups: res.locals.user.groups,
60+
content: {
61+
firstName: res.locals.user.firstName,
62+
lastName: res.locals.user.lastName,
63+
},
64+
};
65+
66+
const jwt = await new jose.SignJWT(userInfo)
67+
.setProtectedHeader({ alg: 'EdDSA' })
68+
.setExpirationTime('10 s') // 10 second JWT expiration
69+
.sign(signingKey);
70+
71+
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
72+
}
73+
```
74+
75+
```python Python
76+
import jwt # pyjwt
77+
import os
78+
79+
from datetime import datetime, timedelta
80+
from fastapi.responses import RedirectResponse
81+
82+
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
83+
84+
@router.get('/auth')
85+
async def return_mintlify_auth_status(current_user):
86+
jwt_token = jwt.encode(
87+
payload={
88+
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
89+
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
90+
'groups': ['admin'] if current_user.is_admin else [],
91+
'content': {
92+
'firstName': current_user.first_name,
93+
'lastName': current_user.last_name,
94+
},
95+
},
96+
key=private_key,
97+
algorithm='EdDSA'
98+
)
99+
100+
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
101+
```
102+
</CodeGroup>

‎settings/authentication-personalization/authentication-setup/mintlify.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: 'Mintlify Dashboard Handshake'
3+
description: 'Use the Mintlify Dashboard to authenticate users'
4+
---
5+
6+
<Info>
7+
This is the documentation for the Mintlify Dashboard **Authentication** Handshake. The Mintlify Dashboard Handshake is not available for Personalization.
8+
</Info>
9+
10+
If your documentation readers are also your documentation editors, you can allow Mintlify to manage access to your documentation. Anyone that can access
11+
your dashboard will automatically be able to access your documentation.
12+
13+
## Implementation
14+
15+
<Steps>
16+
<Step title="Configure your Authentication settings">
17+
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and enable the Mintlify Dashboard Handshake.
18+
</Step>
19+
<Step title="Add users">
20+
Ensure that any users that should be able to view your documentation have been added as users in your
21+
[Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members).
22+
</Step>
23+
</Steps>
24+
25+
## Example
26+
27+
I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
28+
to be internal, and the people that will be viewing my docs are the same people that
29+
contribute to my docs.
30+
31+
To set up authentication with Mintlify, I go to my [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication)
32+
and enable Authentication with the Mintlify Dashboard Handshake.
33+
34+
I then ensure that anyone that should be able to read the docs has been added as a user in
35+
my [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members).

‎settings/authentication-personalization/authentication-setup/oauth.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: 'OAuth 2.0 Handshake'
3+
description: 'Integrate with your OAuth server to enable user login via the Authorization Code flow'
4+
---
5+
6+
<Info>
7+
This is the documentation for the OAuth **Authentication** Handshake. The steps for setting up the [OAuth **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/oauth) are slightly different.
8+
</Info>
9+
10+
If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.
11+
12+
## Implementation
13+
14+
<Steps>
15+
<Step title="Configure your Authentication settings">
16+
Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
17+
18+
- **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
19+
- **Client ID**: An ID for the OAuth 2.0 client to be used.
20+
- **Scopes**: An array of scopes that will be requested.
21+
- **Token URL**: The base URL for the token exchange request.
22+
- **Info API URL** (optional): The endpoint that will be hit to retrieve user info. If omitted, the OAuth flow will only be used to verify identity, and the user info will be empty.
23+
</Step>
24+
<Step title="Configure your OAuth client">
25+
Copy the Redirect URL listed in the [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
26+
</Step>
27+
<Step title="Create your Info API (Optional)">
28+
If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users.
29+
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](../sending-data) format.
30+
31+
Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL
32+
to your OAuth configuration.
33+
</Step>
34+
</Steps>
35+
36+
## Example
37+
38+
I have an existing OAuth server that supports the Authorization Code flow. I want to set up authentication for my docs hosted at `foo.com/docs`.
39+
40+
To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification.
41+
42+
I then go to the Mintlify dashboard settings, navigate to the Authentication settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
43+
- **Authorization URL**: `https://auth.foo.com/authorization`
44+
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
45+
- **Scopes**: `['docs-user-info']`
46+
- **Token URL**: `https://auth.foo.com/exchange`
47+
- **Info API URL**: `https://api.foo.com/docs/user-info`
48+
49+
Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.

‎settings/authentication-personalization/authentication-setup/password.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: 'Password Handshake'
3+
description: 'Use a set of shared passwords to authenticate users'
4+
---
5+
6+
<Info>
7+
This is the documentation for the Password **Authentication** Handshake. The Password Handshake is not available for Personalization.
8+
</Info>
9+
10+
If you don't have strict security requirements, or you don't want to manage a
11+
database of documentation readers, you can use a set of shared passwords to
12+
protect your docs.
13+
14+
## Implementation
15+
16+
<Steps>
17+
<Step title="Add a password">
18+
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and create a password.
19+
</Step>
20+
<Step title="Share your password">
21+
Securely share the password with your documentation readers. That's it!
22+
</Step>
23+
</Steps>
24+
25+
## Example
26+
27+
I want to set up authentication for my docs hosted at `docs.foo.com`. I don't want
28+
to have to keep track of who can and cannot access the docs. My main use case for
29+
authentication is to prevent competitors from snooping - password sharing is secure
30+
enough for my team.
31+
32+
To set up authentication with Mintlify, I go to my Mintlify dashboard and add at
33+
least one password. I then share that password, along with the private docs URL,
34+
with potential customers.

0 commit comments

Comments
 (0)