docs: actual auth

changelog/overview.mdx

@@ -99,7 +99,7 @@ mode: "wide"
 
   ## Filter search based on the current user
 
-  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.
+  When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
 
   ## Custom Prompts for AI Chat
 

mint.json

@@ -111,6 +111,35 @@
     {
       "group": "Configurations",
       "pages": [
+        {
+          "icon": "user-lock",
+          "group": "Auth & Personalization",
+          "pages": [
+            "settings/authentication-personalization/personalization",
+            "settings/authentication-personalization/authentication",
+            "settings/authentication-personalization/authentication-vs-personalization",
+            {
+              "group": "Authentication Setup",
+              "pages": [
+                "settings/authentication-personalization/authentication-setup/choosing-a-handshake",
+                "settings/authentication-personalization/authentication-setup/password",
+                "settings/authentication-personalization/authentication-setup/jwt",
+                "settings/authentication-personalization/authentication-setup/oauth",
+                "settings/authentication-personalization/authentication-setup/mintlify"
+              ]
+            },
+            {
+              "group": "Personalization Setup",
+              "pages": [
+                "settings/authentication-personalization/personalization-setup/choosing-a-handshake",
+                "settings/authentication-personalization/personalization-setup/shared-session",
+                "settings/authentication-personalization/personalization-setup/jwt",
+                "settings/authentication-personalization/personalization-setup/oauth"
+              ]
+            },
+            "settings/authentication-personalization/sending-data"
+          ]
+        },
         "settings/custom-domain",
         "settings/seo",
         "settings/broken-links",
@@ -156,23 +185,6 @@
             "advanced/rest-api/update-status"
           ]
         },
-        {
-          "icon": "user-lock",
-          "group": "User Auth",
-          "pages": [
-            "advanced/user-auth/overview",
-            {
-              "group": "Authenticating",
-              "pages": [
-                "advanced/user-auth/choosing-an-auth-method",
-                "advanced/user-auth/shared-session",
-                "advanced/user-auth/jwt",
-                "advanced/user-auth/oauth"
-              ]
-            },
-            "advanced/user-auth/sending-data"
-          ]
-        },
         "settings/authentication"
       ]
     },

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

@@ -0,0 +1,84 @@
+---
+title: 'Choosing a Handshake'
+description: 'How to decide which auth method is right for your docs'
+---
+
+<Info>
+  This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization-setup/choosing-a-handshake).
+</Info>
+
+Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods:
+
+1. **Password**: Configure a set of global passwords for your documentation site.
+2. **JWT**: Use your own login flow to authenticate your users via a JWT in the URL.
+3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the standard Authorization Code flow.
+4. **Mintlify Dashboard**: Allow all of your dashboard users to access your docs, zero configuration required.
+
+## Prerequisites
+
+<Tabs>
+  <Tab title="Password">
+
+    - Your security requirements allow for password sharing between documentation readers.
+  </Tab>
+  <Tab title="JWT">
+
+    - You have some existing login flow.
+    - You can add a final step in this login flow that creates a JWT and redirects to the docs.
+  </Tab>
+  <Tab title="OAuth 2.0">
+
+    - You have an existing OAuth server that supports the PKCE flow.
+    - You can create a new API endpoint that can be accessed by the returned OAuth access token.
+  </Tab>
+  <Tab title="Mintlify Dashboard">
+
+    - Your documentation readers are also your documentation editors.
+  </Tab>
+</Tabs>
+
+## Pros & Cons
+
+<Tabs>
+  <Tab title="Password">
+    Pros:
+
+    - Super simple setup
+    - No configuration required for adding new users - just share the password
+
+    Cons:
+
+    - Difficult to revoke access to your docs without resetting the password
+    - Lose personalization features, as there is no way to differentiate users with the same password
+  </Tab>
+  <Tab title="JWT">
+    Pros:
+
+    - Reduced risk of API endpoint abuse
+    - Zero CORS configuration
+    - No restrictions on API URLs
+
+    Cons:
+
+    - Must be able to hook into your existing login flow
+  </Tab>
+  <Tab title="OAuth 2.0">
+    Pros:
+
+    - Heightened security standard
+
+    Cons:
+
+    - Requires significant work if setting up OAuth server for the first time
+    - Might be overkill for some applications
+  </Tab>
+  <Tab title="Mintlify Dashboard">
+    Pros:
+
+    - Zero-config setup
+
+    Cons:
+
+    - Requires all docs readers to have an account in your Mintlify dashboard
+  </Tab>
+</Tabs>

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

@@ -0,0 +1,102 @@
+---
+title: 'JWT Handshake'
+description: 'Use a customized login flow to authenticate users'
+---
+
+<Info>
+  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.
+</Info>
+
+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.
+
+## Implementation
+
+<Steps>
+  <Step title="Generate a private key">
+    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+  </Step>
+  <Step title="Create a login flow">
+    Create a login flow that does the following:
+    - Authenticate the user
+    - Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format
+    - Sign the JWT with the secret key, using the EdDSA algorithm
+    - Create a redirect URL back to your docs, including the JWT as the hash
+  </Step>
+  <Step title="Configure your Authentication settings">
+    Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your Authentication settings.
+  </Step>
+</Steps>
+
+## Example
+
+I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
+to be completely separate from my dashboard (or I don’t have a dashboard at all).
+
+To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
+JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
+for my users. At the end of this login flow, once I have verified the identity of the user,
+I create a JWT containing the user’s custom data according to Mintlify’s specification.
+I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
+form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
+
+I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
+Login URL field.
+
+Here's what the code might look like:
+
+<CodeGroup>
+```ts
+import * as jose from 'jose';
+import { Request, Response } from 'express';
+
+const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
+
+const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
+
+export async function handleRequest(req: Request, res: Response) {
+  const userInfo = {
+    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
+    groups: res.locals.user.groups,
+    content: {
+      firstName: res.locals.user.firstName,
+      lastName: res.locals.user.lastName,
+    },
+  };
+
+  const jwt = await new jose.SignJWT(userInfo)
+    .setProtectedHeader({ alg: 'EdDSA' })
+    .setExpirationTime('10 s') // 10 second JWT expiration
+    .sign(signingKey);
+
+  return res.redirect(`https://docs.foo.com#${jwt}`);
+}
+```
+
+```python
+import jwt # pyjwt
+import os
+
+from datetime import datetime, timedelta
+from fastapi.responses import RedirectResponse
+
+private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
+
+@router.get('/auth')
+async def return_mintlify_auth_status(current_user):
+  jwt_token = jwt.encode(
+    payload={
+      'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()),    # 10 second JWT expiration
+      'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
+      'groups': ['admin'] if current_user.is_admin else [],
+      'content': {
+        'firstName': current_user.first_name,
+        'lastName': current_user.last_name,
+      },
+    },
+    key=private_key,
+    algorithm='EdDSA'
+  )
+
+  return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
+```
+</CodeGroup>

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

@@ -0,0 +1,35 @@
+---
+title: 'Mintlify Dashboard Handshake'
+description: 'Use a customized login flow to authenticate users'
+---
+
+<Info>
+  This is the documentation for the Mintlify Dashboard **Authentication** Handshake. The Mintlify Dashboard Handshake is not available for Personalization.
+</Info>
+
+If your documentation readers are also your documentation editors, you can allow Mintlify to manage access to your documentation. Anyone that can access
+your dashboard will automatically be able to access your documentation.
+
+## Implementation
+
+<Steps>
+  <Step title="Configure your Authentication settings">
+    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and enable the Mintlify Dashboard Handshake.
+  </Step>
+  <Step title="Add users">
+    Ensure that any users that should be able to view your documentation have been added as users in your
+    [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/organization/members).
+  </Step>
+</Steps>
+
+## Example
+
+I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
+to be internal, and the people that will be viewing my docs are the same people that
+contribute to my docs.
+
+To set up authentication with Mintlify, I go to my [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication)
+and enable Authentication with the Mintlify Dashboard Handshake.
+
+I then ensure that anyone that should be able to read the docs has been added as a user in
+my [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/organization/members).

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

@@ -0,0 +1,49 @@
+---
+title: 'OAuth 2.0 Handshake'
+description: 'Integrate with your OAuth server to enable user login via the PKCE flow'
+---
+
+<Info>
+  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.
+</Info>
+
+If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.
+
+## Implementation
+
+<Steps>
+  <Step title="Configure your Authentication settings">
+    Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication), select the OAuth option, and fill out the required fields:
+
+    - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
+    - **Client ID**: An ID for the OAuth 2.0 client to be used.
+    - **Scopes**: An array of scopes that will be requested.
+    - **Token URL**: The base URL for the token exchange request.
+    - **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.
+  </Step>
+  <Step title="Configure your OAuth client">
+    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.
+  </Step>
+  <Step title="Create your Info API (Optional)">
+    If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users.
+    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.
+
+    Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the Info API URL
+    to your OAuth configuration.
+  </Step>
+</Steps>
+
+## Example
+
+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`.
+
+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.
+
+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:
+- **Authorization URL**: `https://auth.foo.com/authorization`
+- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
+- **Scopes**: `['docs-user-info']`
+- **Token URL**: `https://auth.foo.com/exchange`
+- **Info API URL**: `https://api.foo.com/docs/user-info`
+
+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

@@ -0,0 +1,34 @@
+---
+title: 'Password Handshake'
+description: 'Use a set of shared passwords to authenticate users'
+---
+
+<Info>
+  This is the documentation for the Password **Authentication** Handshake. The Password Handshake is not available for Personalization.
+</Info>
+
+If you don't have strict security requirements, or you don't want to manage a
+database of documentation readers, you can use a set of shared passwords to
+protect your docs.
+
+## Implementation
+
+<Steps>
+  <Step title="Add a password">
+    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and create a password.
+  </Step>
+  <Step title="Share your password">
+    Securely share the password with your documentation readers. That's it!
+  </Step>
+</Steps>
+
+## Example
+
+I want to set up authentication for my docs hosted at `docs.foo.com`. I don't want
+to have to keep track of who can and cannot access the docs. My main use case for
+authentication is to prevent competitors from snooping - password sharing is secure
+enough for my team.
+
+To set up authentication with Mintlify, I go to my Mintlify dashboard and add at
+least one password. I then share that password, along with the private docs URL,
+with potential customers.