Skip to content

Commit 2c9f0f5

Browse files
rpmccarterrpmccarter
committed
update authentication handshakes
1 parent 0a51361 commit 2c9f0f5

File tree

5 files changed

+149
-18
lines changed

5 files changed

+149
-18
lines changed

‎mint.json‎

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,34 @@
111111
{
112112
"group": "Configurations",
113113
"pages": [
114+
{
115+
"icon": "user-lock",
116+
"group": "Authentication & Personalization",
117+
"pages": [
118+
"settings/authentication-personalization/shared-features",
119+
"settings/authentication-personalization/authentication-vs-personalization",
120+
{
121+
"group": "Authentication Setup",
122+
"pages": [
123+
"settings/authentication-personalization/authentication/choosing-a-handshake",
124+
"settings/authentication-personalization/authentication/password",
125+
"settings/authentication-personalization/authentication/jwt",
126+
"settings/authentication-personalization/authentication/oauth",
127+
"settings/authentication-personalization/authentication/mintlify"
128+
]
129+
},
130+
{
131+
"group": "Personalization Setup",
132+
"pages": [
133+
"settings/authentication-personalization/personalization/choosing-a-handshake",
134+
"settings/authentication-personalization/personalization/shared-session",
135+
"settings/authentication-personalization/personalization/jwt",
136+
"settings/authentication-personalization/personalization/oauth"
137+
]
138+
},
139+
"settings/authentication-personalization/sending-data"
140+
]
141+
},
114142
"settings/custom-domain",
115143
"settings/seo",
116144
"settings/broken-links",
@@ -156,23 +184,6 @@
156184
"advanced/rest-api/update-status"
157185
]
158186
},
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-
},
176187
"settings/authentication"
177188
]
178189
},

‎settings/authentication-personalization/authentication-vs-personalization.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: 'Authentication vs Personalization'
3-
description: 'How to determine which feature is best for you'
3+
description: 'How to determine which product is best for you'
44
---
55

66
Mintlify offers both Authentication and Personalization. For the most part, Authentication is
@@ -36,9 +36,11 @@ Personalization offers one additional Handshake method:
3636
- **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint
3737
that returns data for already-authenticated users.
3838

39+
{/*
3940
### Pricing
4041
4142
Mintlify strives to ensure that your private content stays private, full stop. Because this level
4243
of security is not easy to achieve, Authentication is an enterprise feature. If an enterprise plan
4344
doesn't make sense for you, consider whether Personalization might meet your needs. Personalization
4445
is available on all plans.
46+
*/}

‎settings/authentication-personalization/authentication/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 a customized login flow 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="Generate a private key">
17+
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/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/mintlify/mintlify/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/mintlify/mintlify/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/mintlify/mintlify/settings/organization/members).

‎settings/authentication-personalization/authentication/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 PKCE 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/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 User Auth settings">
16+
Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/mintlify/mintlify/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/mintlify/mintlify/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/mintlify/mintlify/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 PKCE 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 User Auth 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/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/mintlify/mintlify/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)