Skip to content

Commit 93e6772

Browse files
ethanpalmethanpalm
authored
Consolidate auth docs (#999)
* hide overview * reorder auth methods * combine partial and full auth * format JSON example * move Sending data into Personalization * set up redirects * add more conceptual info to personalization * move longer example to later in page * update all ParamFields * copyedit * copyedit overview * appease the broken link checker * add OIDC * add logout URL
1 parent 97b3768 commit 93e6772

File tree

7 files changed

+363
-365
lines changed

7 files changed

+363
-365
lines changed

‎authentication-personalization/authentication-setup.mdx

Lines changed: 170 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,153 @@
11
---
22
title: "Authentication setup"
3-
description: "Guarantee privacy of your docs by authenticating users"
3+
description: "Control the privacy of your docs by authenticating users"
44
icon: "file-lock"
55
keywords: ['auth']
66
---
7-
Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method.
8-
9-
**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options.
107

118
<Info>
129
[Pro plans](https://mintlify.com/pricing?ref=authentication) include password authentication.
1310

1411
[Enterprise plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods.
1512
</Info>
1613

14+
Authentication requires users to log in before accessing your documentation.
15+
16+
## Authentication modes
17+
18+
Choose between full and partial authentication modes based on your access control needs.
19+
20+
**Full authentication**: All pages are protected. Users must log in before accessing any content.
21+
22+
**Partial authentication**: Some pages are publicly viewable while others require authentication. Users can browse public content freely and authenticate only when accessing protected pages.
23+
24+
When configuring any handshake method below, you'll select either **Full authentication** or **Partial authentication** in your dashboard settings.
25+
1726
## Configuring authentication
1827

1928
Select the handshake method that you want to configure.
2029

2130
<Tabs>
31+
<Tab title="Password">
32+
<Info>
33+
Password authentication provides access control only and does **not** support content personalization.
34+
</Info>
35+
36+
### Prerequisites
37+
38+
* Your security requirements allow sharing passwords among users.
39+
40+
### Implementation
41+
42+
<Steps>
43+
<Step title="Create a password.">
44+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
45+
2. Select **Full Authentication** or **Partial Authentication**.
46+
3. Select **Password**.
47+
4. Enter a secure password.
48+
5. Select **Save changes**.
49+
</Step>
50+
<Step title="Distribute access.">
51+
Securely share the password and documentation URL with authorized users.
52+
</Step>
53+
</Steps>
54+
55+
## Example
56+
57+
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.
58+
59+
**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!
60+
</Tab>
61+
<Tab title="Mintlify Dashboard">
62+
### Prerequisites
63+
64+
* Your documentation users are also your documentation editors.
65+
66+
### Implementation
67+
68+
<Steps>
69+
<Step title="Enable Mintlify dashboard authentication.">
70+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
71+
2. Select **Full Authentication** or **Partial Authentication**.
72+
3. Select **Mintlify Auth**.
73+
4. Select **Enable Mintlify Auth**.
74+
</Step>
75+
<Step title="Add authorized users.">
76+
1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members).
77+
2. Add each person who should have access to your documentation.
78+
3. Assign appropriate roles based on their editing permissions.
79+
</Step>
80+
</Steps>
81+
82+
### Example
83+
84+
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.
85+
86+
**Enable Mintlify authentication** in your dashboard settings.
87+
88+
**Verify team access** by checking that all team members are added to your organization.
89+
</Tab>
90+
<Tab title="OAuth 2.0">
91+
### Prerequisites
92+
93+
* An OAuth or OIDC server that supports the Authorization Code Flow.
94+
* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).
95+
96+
### Implementation
97+
98+
<Steps>
99+
<Step title="Configure your OAuth settings.">
100+
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
101+
2. Select **Full Authentication** or **Partial Authentication**.
102+
3. Select **OAuth** and configure these fields:
103+
* **Authorization URL**: Your OAuth endpoint.
104+
* **Client ID**: Your OAuth 2.0 client identifier.
105+
* **Client Secret**: Your OAuth 2.0 client secret.
106+
* **Scopes**: Permissions to request. Use multiple scopes if you need different access levels.
107+
* **Token URL**: Your OAuth token exchange endpoint.
108+
* **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.
109+
* **Logout URL**: The native logout URL for your OAuth provider. If your provider has a `returnTo` or similar parameter, point it back to your docs URL.
110+
4. Select **Save changes**.
111+
</Step>
112+
<Step title="Configure your OAuth server.">
113+
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
114+
2. Add the redirect URL as an authorized redirect URL for your OAuth server.
115+
</Step>
116+
<Step title="Create your user info endpoint (optional).">
117+
To enable personalization features, create an API endpoint that:
118+
* Accepts OAuth access tokens for authentication.
119+
* Returns user data in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
120+
121+
Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
122+
</Step>
123+
</Steps>
124+
125+
### Example
126+
127+
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.
128+
129+
**Configure your OAuth server details** in your dashboard:
130+
- **Authorization URL**: `https://auth.foo.com/authorization`
131+
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
132+
- **Scopes**: `['docs-user-info']`
133+
- **Token URL**: `https://auth.foo.com/exchange`
134+
- **Info API URL**: `https://api.foo.com/docs/user-info`
135+
- **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs`
136+
137+
**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:
138+
139+
```json
140+
{
141+
"content": {
142+
"firstName": "Jane",
143+
"lastName": "Doe"
144+
},
145+
"groups": ["engineering", "admin"]
146+
}
147+
```
148+
149+
**Configure your OAuth server to allow redirects** to your callback URL.
150+
</Tab>
22151
<Tab title="JWT">
23152
### Prerequisites
24153

@@ -121,122 +250,50 @@ When an unauthenticated user tries to access a protected page, their intended de
121250
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
122251
4. User lands in their original destination.
123252
</Tab>
124-
<Tab title="OAuth 2.0">
125-
### Prerequisites
253+
</Tabs>
126254

127-
* An OAuth server that supports the Authorization Code Flow.
128-
* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).
255+
## Making pages public
129256

130-
### Implementation
257+
When using partial authentication, all pages are protected by default. You can make specific pages viewable without authentication at the page or group level with the `public` property.
131258

132-
<Steps>
133-
<Step title="Configure your OAuth settings.">
134-
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
135-
2. Select **Full Authentication** or **Partial Authentication**.
136-
3. Select **OAuth** and configure these fields:
137-
* **Authorization URL**: Your OAuth endpoint.
138-
* **Client ID**: Your OAuth 2.0 client identifier.
139-
* **Client Secret**: Your OAuth 2.0 client secret.
140-
* **Scopes**: Permissions to request. Use multiple scopes if you need different access levels.
141-
* **Token URL**: Your OAuth token exchange endpoint.
142-
* **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.
143-
4. Select **Save changes**.
144-
</Step>
145-
<Step title="Configure your OAuth server.">
146-
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
147-
2. Add the redirect URL as an authorized redirect URL for your OAuth server.
148-
</Step>
149-
<Step title="Create your user info endpoint (optional).">
150-
To enable personalization features, create an API endpoint that:
151-
* Accepts OAuth access tokens for authentication.
152-
* Returns user data in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information.
153-
154-
Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
155-
</Step>
156-
</Steps>
259+
### Page level
157260

158-
### Example
261+
To make a page public, add `public: true` to the page's frontmatter.
159262

160-
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.
263+
```mdx Public page example
264+
---
265+
title: "Public page"
266+
public: true
267+
---
268+
```
161269

162-
**Configure your OAuth server details** in your dashboard:
163-
- **Authorization URL**: `https://auth.foo.com/authorization`
164-
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
165-
- **Scopes**: `['docs-user-info']`
166-
- **Token URL**: `https://auth.foo.com/exchange`
167-
- **Info API URL**: `https://api.foo.com/docs/user-info`
270+
### Group level
168271

169-
**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:
272+
To make all pages in a group public, add `"public": true` beneath the group's name in the `navigation` object of your `docs.json`.
170273

171-
```json
274+
```json Public group example
172275
{
173-
"content": {
174-
"firstName": "Jane",
175-
"lastName": "Doe"
176-
},
177-
"groups": ["engineering", "admin"]
276+
"navigation": {
277+
"groups": [
278+
{
279+
"group": "Public group",
280+
"public": true,
281+
"icon": "play",
282+
"pages": [
283+
"quickstart",
284+
"installation",
285+
"settings"
286+
]
287+
},
288+
{
289+
"group": "Private group",
290+
"icon": "pause",
291+
"pages": [
292+
"private-information",
293+
"secret-settings"
294+
]
295+
}
296+
]
297+
}
178298
}
179-
```
180-
181-
**Configure your OAuth server to allow redirects** to your callback URL.
182-
</Tab>
183-
<Tab title="Mintlify Dashboard">
184-
### Prerequisites
185-
186-
* Your documentation users are also your documentation editors.
187-
188-
### Implementation
189-
190-
<Steps>
191-
<Step title="Enable Mintlify dashboard authentication.">
192-
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
193-
2. Select **Full Authentication** or **Partial Authentication**.
194-
3. Select **Mintlify Auth**.
195-
4. Select **Enable Mintlify Auth**.
196-
</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.
201-
</Step>
202-
</Steps>
203-
204-
### Example
205-
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.
207-
208-
**Enable Mintlify authentication** in your dashboard settings.
209-
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>
216-
217-
### Prerequisites
218-
219-
* Your security requirements allow sharing passwords among users.
220-
221-
### Implementation
222-
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>
235-
236-
## Example
237-
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.
239-
240-
**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!
241-
</Tab>
242-
</Tabs>
299+
```

0 commit comments

Comments
 (0)