From 1efa07a7de697cce7ee2c9856b75e45263f07def Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 13:07:46 -0800 Subject: [PATCH 01/17] authentication-related pages --- .../authentication-vs-personalization.mdx | 44 ++++++++++ .../authentication/choosing-a-handshake.mdx | 84 +++++++++++++++++++ .../sending-data.mdx | 2 +- .../shared-features.mdx | 81 ++++++++++++++++++ 4 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 settings/authentication-personalization/authentication-vs-personalization.mdx create mode 100644 settings/authentication-personalization/authentication/choosing-a-handshake.mdx rename {advanced/user-auth => settings/authentication-personalization}/sending-data.mdx (84%) create mode 100644 settings/authentication-personalization/shared-features.mdx diff --git a/settings/authentication-personalization/authentication-vs-personalization.mdx b/settings/authentication-personalization/authentication-vs-personalization.mdx new file mode 100644 index 000000000..4b0d9f147 --- /dev/null +++ b/settings/authentication-personalization/authentication-vs-personalization.mdx @@ -0,0 +1,44 @@ +--- +title: 'Authentication vs Personalization' +description: 'How to determine which feature is best for you' +--- + +Mintlify offers both Authentication and Personalization. For the most part, Authentication is +just Personalization + privacy. However, there are some key differences that are important to +be aware of, from most important to least: + +### Security Guarantees + +Authentication is a fully-fledged private documentation solution. Every aspect of your docs, +including page content, images, search results, and AI chat features, are completely inaccessible to +unauthenticated users. + +Personalization, on the other hand, offers no security guarantees for your documentation content. +All page content, images, search results, and AI chat features can be accessed by the public. Even +if you are using the hidden pages feature of Personalization, a motivated attacker would still +be able to access the content of a hidden page. + +### Handshake Methods + +Due to the difference in security requirements for Authentication and Personalization, different +handshake methods are available for each. Both methods offer a JWT and OAuth Handshake, although +the setup steps are slightly different. + +Authentication offers two additional Handshake methods: + +- **Password Handshake**, which protects your website with a single configurable global password. + +- **Mintlify Dashboard Handshake**, which will allow users to view your documentation only if they have +access to your dashboard. + +Personalization offers one additional Handshake method: + +- **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint +that returns data for already-authenticated users. + +### Pricing + +Mintlify strives to ensure that your private content stays private, full stop. Because this level +of security is not easy to achieve, Authentication is an enterprise feature. If an enterprise plan +doesn't make sense for you, consider whether Personalization might meet your needs. Personalization +is available on all plans. diff --git a/settings/authentication-personalization/authentication/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication/choosing-a-handshake.mdx new file mode 100644 index 000000000..19fc1c360 --- /dev/null +++ b/settings/authentication-personalization/authentication/choosing-a-handshake.mdx @@ -0,0 +1,84 @@ +--- +title: 'Choosing a Handshake' +description: 'How to decide which auth method is right for your docs' +--- + + + This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization/choosing-a-handshake). + + +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 + + + + + - Your security requirements allow for password sharing between documentation readers. + + + + - 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. + + + + - 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. + + + + - Your documentation readers are also your documentation editors. + + + +## Pros & Cons + + + + 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 + + + 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 + + + Pros: + + - Heightened security standard + + Cons: + + - Requires significant work if setting up OAuth server for the first time + - Might be overkill for some applications + + + Pros: + + - Zero-config setup + + Cons: + + - Requires all docs readers to have an account in your Mintlify dashboard + + diff --git a/advanced/user-auth/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx similarity index 84% rename from advanced/user-auth/sending-data.mdx rename to settings/authentication-personalization/sending-data.mdx index 019dc0581..8610cafba 100644 --- a/advanced/user-auth/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -24,7 +24,7 @@ type UserInfo = { type="number" > The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted. - For JWT Auth: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks. + For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks. To access this feature, first create an account at the Mintlify dashboard. +: userContext.org.plan !== 'enterprise' + ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. + : <>To request this feature for your enterprise org, contact our team. +} + +```jsx +User Auth is an enterprise feature. { + userContext.org === undefined + ? <>To access this feature, first create an account at the Mintlify dashboard. + : userContext.org.plan !== 'enterprise' + ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. + : <>To request this feature for your enterprise org, contact our team. +} +``` + + + The information in `userContext` is only available after a user has logged in. For logged out users, the value of `userContext` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}` + + +### Prefilling API Keys + +If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground. + +### Showing/Hiding Pages + +By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. +When determining which pages to show to the user, Mintlify will check which groups the user belongs to. +If the user is not in any of the groups listed in the page metadata, the page will not be shown. + +```md +--- +title: 'Managing Your Users' +description: 'Adding and removing users from your organization' +groups: ['admin'] +--- +``` + +Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata: + +| | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo | +| :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: | +| `groups` not in metadata | ✅ | ✅ | ✅ | +| `groups: []` in metadata | ❌ | ❌ | ❌ | +| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ | + +Note that an empty array in the page metadata is interpreted as "No groups should see this page." \ No newline at end of file From 1862050a6f65e4578e1ef3579e68b26d992acd1c Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 13:08:05 -0800 Subject: [PATCH 02/17] adjust SSO copy --- settings/authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/authentication.mdx b/settings/authentication.mdx index 38de095c8..35bb3eddc 100644 --- a/settings/authentication.mdx +++ b/settings/authentication.mdx @@ -1,6 +1,6 @@ --- title: "Single Sign-On (SSO)" -description: "Customize how your team can login to Mintlify" +description: "Customize how your team can login to your Mintlify dashboard" icon: 'user-unlock' --- From d3cce1091641518c09c647162db6eefd02da1a03 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 13:13:58 -0800 Subject: [PATCH 03/17] adjust personalization handshake methods --- advanced/user-auth/overview.mdx | 88 ------------------- .../personalization/choosing-a-handshake.mdx | 8 +- .../personalization}/jwt.mdx | 11 ++- .../personalization}/oauth.mdx | 10 ++- .../personalization}/shared-session.mdx | 8 +- .../sending-data.mdx | 2 +- 6 files changed, 28 insertions(+), 99 deletions(-) delete mode 100644 advanced/user-auth/overview.mdx rename advanced/user-auth/choosing-an-auth-method.mdx => settings/authentication-personalization/personalization/choosing-a-handshake.mdx (90%) rename {advanced/user-auth => settings/authentication-personalization/personalization}/jwt.mdx (83%) rename {advanced/user-auth => settings/authentication-personalization/personalization}/oauth.mdx (77%) rename {advanced/user-auth => settings/authentication-personalization/personalization}/shared-session.mdx (91%) diff --git a/advanced/user-auth/overview.mdx b/advanced/user-auth/overview.mdx deleted file mode 100644 index c4d4da70f..000000000 --- a/advanced/user-auth/overview.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 'Introduction' -description: 'Give your users a personalized docs experience' ---- - -User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. Your users. - -Example use cases: - -1. **Customize MDX content** with a user's information, such as their name, plan, or title. - -2. **Prefill API keys** in the API Playground for streamlined use. - -3. **Selectively show pages** in the navigation based on a user's groups. - -## What *isn't* User Auth - -At this time, User Auth is not meant for the following use cases: - -1. **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it. - -2. **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data. - -If you are interested in private docs content, [contact our team](mailto:sales@mintlify.com) to explore solutions. - -## How to Use - -### Customizing MDX Content - -When writing content, you can use the `userContext` variable to access the information you have sent to your docs. Here's a simple example: - -Hello, {userContext.name ?? 'reader'}! - -```jsx -Hello, {userContext.name ?? 'reader'}! -``` - -This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer's existing plan: - -User Auth is an enterprise feature. { -userContext.org === undefined -? <>To access this feature, first create an account at the Mintlify dashboard. -: userContext.org.plan !== 'enterprise' - ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. -} - -```jsx -User Auth is an enterprise feature. { - userContext.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. - : userContext.org.plan !== 'enterprise' - ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. -} -``` - - - The information in `userContext` is only available after a user has logged in. For logged out users, the value of `userContext` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}` - - -### Prefilling API Keys - -If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground. - -### Showing/Hiding Pages - -By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. -When determining which pages to show to the user, Mintlify will check which groups the user belongs to. -If the user is not in any of the groups listed in the page metadata, the page will not be shown. - -```md ---- -title: 'Managing Your Users' -description: 'Adding and removing users from your organization' -groups: ['admin'] ---- -``` - -Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata: - -| | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo | -| :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: | -| `groups` not in metadata | ✅ | ✅ | ✅ | -| `groups: []` in metadata | ❌ | ❌ | ❌ | -| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ | - -Note that an empty array in the page metadata is interpreted as "No groups should see this page." \ No newline at end of file diff --git a/advanced/user-auth/choosing-an-auth-method.mdx b/settings/authentication-personalization/personalization/choosing-a-handshake.mdx similarity index 90% rename from advanced/user-auth/choosing-an-auth-method.mdx rename to settings/authentication-personalization/personalization/choosing-a-handshake.mdx index 9cc97c080..4f65f2367 100644 --- a/advanced/user-auth/choosing-an-auth-method.mdx +++ b/settings/authentication-personalization/personalization/choosing-a-handshake.mdx @@ -1,9 +1,13 @@ --- -title: 'Choosing an Auth Method' +title: 'Choosing a Handshake' description: 'How to decide which auth method is right for your docs' --- -Before your users can access personalized content, they must be authenticated. Mintlify supports three methods of authenticating users: + + This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication/choosing-a-handshake). + + +Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods: 1. **Shared Session**: Utilize the same session token used by your dashboard to authenticate users. 2. **JWT**: Use your own login flow to send user info to your docs via a JWT in the URL. diff --git a/advanced/user-auth/jwt.mdx b/settings/authentication-personalization/personalization/jwt.mdx similarity index 83% rename from advanced/user-auth/jwt.mdx rename to settings/authentication-personalization/personalization/jwt.mdx index 3385f0485..799c2feca 100644 --- a/advanced/user-auth/jwt.mdx +++ b/settings/authentication-personalization/personalization/jwt.mdx @@ -3,23 +3,28 @@ title: 'JWT Auth' description: 'Use a customized login flow to authenticate users' --- + + This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication/jwt) are slightly different. + + + 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 send user info to your docs via a JWT in the URL. ## Implementation - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend. + 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. 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 + - Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format - Sign the JWT with the secret, using the EdDSA algorithm - Create a redirect URL back to your docs, including the JWT as the hash - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the login URL to your User Auth settings. + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your User Auth settings. diff --git a/advanced/user-auth/oauth.mdx b/settings/authentication-personalization/personalization/oauth.mdx similarity index 77% rename from advanced/user-auth/oauth.mdx rename to settings/authentication-personalization/personalization/oauth.mdx index 98251eb9f..83c196a47 100644 --- a/advanced/user-auth/oauth.mdx +++ b/settings/authentication-personalization/personalization/oauth.mdx @@ -3,16 +3,20 @@ title: 'OAuth 2.0' description: 'Integrate with your OAuth server to enable user login via the PKCE flow' --- + + This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication/oauth) are slightly different. + + If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. ## Implementation - 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. Take note of the scope or scopes required to access this endpoint. + 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. Take note of the scope or scopes required to access this endpoint. - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select the OAuth option, and fill out the required fields: + Go to your [Mintlify dashboard 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. @@ -21,7 +25,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr - **Info API URL**: The endpoint that will be hit to retrieve user info. - Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add it as an authorized redirect URL for your OAuth server. + Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add it as an authorized redirect URL for your OAuth server. diff --git a/advanced/user-auth/shared-session.mdx b/settings/authentication-personalization/personalization/shared-session.mdx similarity index 91% rename from advanced/user-auth/shared-session.mdx rename to settings/authentication-personalization/personalization/shared-session.mdx index d2925a269..6f95f2afa 100644 --- a/advanced/user-auth/shared-session.mdx +++ b/settings/authentication-personalization/personalization/shared-session.mdx @@ -3,13 +3,17 @@ title: 'Shared Session Auth' description: 'Seamlessly share user sessions between your dashboard and your docs' --- + + This is the documentation for the Shared Session **Personalization** Handshake. The Shared Session Handshake is not available for Authentication. + + This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. ## Implementation - Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](./sending-data) format. + Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](../sending-data) format. If the API domain does not *exactly match* the docs domain: - Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`) @@ -19,7 +23,7 @@ This method utilizes the session authentication info already stored in your user - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the API URL and your Login URL to your User Auth settings. + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the API URL and your Login URL to your User Auth settings. diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index 8610cafba..c5a685446 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -3,7 +3,7 @@ title: 'Sending Data' description: 'The types and shape of user data you can send to Mintlify' --- -Depending on your authentication configuration, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both: +Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both: ```tsx type UserInfo = { From 0a5136110fbbaa9bdb448fd7639965f769379d3e Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 14:29:26 -0800 Subject: [PATCH 04/17] auth jwt and update titles --- .../authentication/jwt.mdx | 102 ++++++++++++++++++ .../personalization/jwt.mdx | 4 +- .../personalization/oauth.mdx | 2 +- .../personalization/shared-session.mdx | 2 +- .../shared-features.mdx | 11 +- 5 files changed, 112 insertions(+), 9 deletions(-) create mode 100644 settings/authentication-personalization/authentication/jwt.mdx diff --git a/settings/authentication-personalization/authentication/jwt.mdx b/settings/authentication-personalization/authentication/jwt.mdx new file mode 100644 index 000000000..963c4dead --- /dev/null +++ b/settings/authentication-personalization/authentication/jwt.mdx @@ -0,0 +1,102 @@ +--- +title: 'JWT Handshake' +description: 'Use a customized login flow to authenticate users' +--- + + + This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization/jwt) are slightly different. + + +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 + + + + 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. + + + 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 + + + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your User Auth settings. + + + +## 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: + + +```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) +``` + diff --git a/settings/authentication-personalization/personalization/jwt.mdx b/settings/authentication-personalization/personalization/jwt.mdx index 799c2feca..e4e599f3e 100644 --- a/settings/authentication-personalization/personalization/jwt.mdx +++ b/settings/authentication-personalization/personalization/jwt.mdx @@ -1,5 +1,5 @@ --- -title: 'JWT Auth' +title: 'JWT Handshake' description: 'Use a customized login flow to authenticate users' --- @@ -20,7 +20,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs 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, using the EdDSA algorithm + - 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 diff --git a/settings/authentication-personalization/personalization/oauth.mdx b/settings/authentication-personalization/personalization/oauth.mdx index 83c196a47..09da1a4f6 100644 --- a/settings/authentication-personalization/personalization/oauth.mdx +++ b/settings/authentication-personalization/personalization/oauth.mdx @@ -1,5 +1,5 @@ --- -title: 'OAuth 2.0' +title: 'OAuth 2.0 Handshake' description: 'Integrate with your OAuth server to enable user login via the PKCE flow' --- diff --git a/settings/authentication-personalization/personalization/shared-session.mdx b/settings/authentication-personalization/personalization/shared-session.mdx index 6f95f2afa..aaf7d4578 100644 --- a/settings/authentication-personalization/personalization/shared-session.mdx +++ b/settings/authentication-personalization/personalization/shared-session.mdx @@ -1,5 +1,5 @@ --- -title: 'Shared Session Auth' +title: 'Shared Session Handshake' description: 'Seamlessly share user sessions between your dashboard and your docs' --- diff --git a/settings/authentication-personalization/shared-features.mdx b/settings/authentication-personalization/shared-features.mdx index f7a5d88a5..7349c70bc 100644 --- a/settings/authentication-personalization/shared-features.mdx +++ b/settings/authentication-personalization/shared-features.mdx @@ -3,12 +3,13 @@ title: 'Shared Features' description: 'A list of features offered by both Authentication and Personalization' --- -Authentication can be thought of as Personalization + privacy, which means that all -Personalization features are also Authentication features. This page will explain the -different features of Personalization, all of which also apply to Authentication. +Personalization refers to a suite of features that allow you to customize your +documentation experience based on some information about the user. Authentication +can be thought of as Personalization + privacy. -Personalization allow you to identify your users so that you can personalize docs -content for them. Example use cases: +This page will explain the different features of Personalization, all of which +are also available with Authentication. There are three major features of +Personalization: - **Customize MDX content** with a user's information, such as their name, plan, or title. From 2c9f0f5dd1d0ae8bfb3a6d0f2606645078cc015d Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 14:52:59 -0800 Subject: [PATCH 05/17] update authentication handshakes --- mint.json | 45 ++++++++++------- .../authentication-vs-personalization.mdx | 4 +- .../authentication/mintlify.mdx | 35 +++++++++++++ .../authentication/oauth.mdx | 49 +++++++++++++++++++ .../authentication/password.mdx | 34 +++++++++++++ 5 files changed, 149 insertions(+), 18 deletions(-) create mode 100644 settings/authentication-personalization/authentication/mintlify.mdx create mode 100644 settings/authentication-personalization/authentication/oauth.mdx create mode 100644 settings/authentication-personalization/authentication/password.mdx diff --git a/mint.json b/mint.json index 502a9e4d0..9cdaef81b 100644 --- a/mint.json +++ b/mint.json @@ -111,6 +111,34 @@ { "group": "Configurations", "pages": [ + { + "icon": "user-lock", + "group": "Authentication & Personalization", + "pages": [ + "settings/authentication-personalization/shared-features", + "settings/authentication-personalization/authentication-vs-personalization", + { + "group": "Authentication Setup", + "pages": [ + "settings/authentication-personalization/authentication/choosing-a-handshake", + "settings/authentication-personalization/authentication/password", + "settings/authentication-personalization/authentication/jwt", + "settings/authentication-personalization/authentication/oauth", + "settings/authentication-personalization/authentication/mintlify" + ] + }, + { + "group": "Personalization Setup", + "pages": [ + "settings/authentication-personalization/personalization/choosing-a-handshake", + "settings/authentication-personalization/personalization/shared-session", + "settings/authentication-personalization/personalization/jwt", + "settings/authentication-personalization/personalization/oauth" + ] + }, + "settings/authentication-personalization/sending-data" + ] + }, "settings/custom-domain", "settings/seo", "settings/broken-links", @@ -156,23 +184,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" ] }, diff --git a/settings/authentication-personalization/authentication-vs-personalization.mdx b/settings/authentication-personalization/authentication-vs-personalization.mdx index 4b0d9f147..4b0dd5a54 100644 --- a/settings/authentication-personalization/authentication-vs-personalization.mdx +++ b/settings/authentication-personalization/authentication-vs-personalization.mdx @@ -1,6 +1,6 @@ --- title: 'Authentication vs Personalization' -description: 'How to determine which feature is best for you' +description: 'How to determine which product is best for you' --- Mintlify offers both Authentication and Personalization. For the most part, Authentication is @@ -36,9 +36,11 @@ Personalization offers one additional Handshake method: - **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint that returns data for already-authenticated users. +{/* ### Pricing Mintlify strives to ensure that your private content stays private, full stop. Because this level of security is not easy to achieve, Authentication is an enterprise feature. If an enterprise plan doesn't make sense for you, consider whether Personalization might meet your needs. Personalization is available on all plans. +*/} diff --git a/settings/authentication-personalization/authentication/mintlify.mdx b/settings/authentication-personalization/authentication/mintlify.mdx new file mode 100644 index 000000000..f9c192c12 --- /dev/null +++ b/settings/authentication-personalization/authentication/mintlify.mdx @@ -0,0 +1,35 @@ +--- +title: 'Mintlify Dashboard Handshake' +description: 'Use a customized login flow to authenticate users' +--- + + + This is the documentation for the Mintlify Dashboard **Authentication** Handshake. The Mintlify Dashboard Handshake is not available for Personalization. + + +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 + + + + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and enable the Mintlify Dashboard Handshake. + + + 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). + + + +## 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). diff --git a/settings/authentication-personalization/authentication/oauth.mdx b/settings/authentication-personalization/authentication/oauth.mdx new file mode 100644 index 000000000..083abc0a7 --- /dev/null +++ b/settings/authentication-personalization/authentication/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' +--- + + + 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. + + +If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience. + +## Implementation + + + + 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. + + + 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. + + + 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. + + + +## 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 User Auth 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. diff --git a/settings/authentication-personalization/authentication/password.mdx b/settings/authentication-personalization/authentication/password.mdx new file mode 100644 index 000000000..6f8ed9a2d --- /dev/null +++ b/settings/authentication-personalization/authentication/password.mdx @@ -0,0 +1,34 @@ +--- +title: 'Password Handshake' +description: 'Use a set of shared passwords to authenticate users' +--- + + + This is the documentation for the Password **Authentication** Handshake. The Password Handshake is not available for Personalization. + + +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 + + + + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and create a password. + + + Securely share the password with your documentation readers. That's it! + + + +## 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. From a09869943da2b10cbf76dfdc0267ebee61af4d87 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:03:08 -0800 Subject: [PATCH 06/17] update paths and separate auth and personalization features --- mint.json | 21 ++++++++++--------- .../choosing-a-handshake.mdx | 2 +- .../jwt.mdx | 2 +- .../mintlify.mdx | 0 .../oauth.mdx | 2 +- .../password.mdx | 0 .../authentication.mdx | 17 +++++++++++++++ .../choosing-a-handshake.mdx | 2 +- .../jwt.mdx | 2 +- .../oauth.mdx | 2 +- .../shared-session.mdx | 0 ...hared-features.mdx => personalization.mdx} | 12 ++++------- 12 files changed, 38 insertions(+), 24 deletions(-) rename settings/authentication-personalization/{authentication => authentication-setup}/choosing-a-handshake.mdx (96%) rename settings/authentication-personalization/{authentication => authentication-setup}/jwt.mdx (97%) rename settings/authentication-personalization/{authentication => authentication-setup}/mintlify.mdx (100%) rename settings/authentication-personalization/{authentication => authentication-setup}/oauth.mdx (98%) rename settings/authentication-personalization/{authentication => authentication-setup}/password.mdx (100%) create mode 100644 settings/authentication-personalization/authentication.mdx rename settings/authentication-personalization/{personalization => personalization-setup}/choosing-a-handshake.mdx (97%) rename settings/authentication-personalization/{personalization => personalization-setup}/jwt.mdx (97%) rename settings/authentication-personalization/{personalization => personalization-setup}/oauth.mdx (98%) rename settings/authentication-personalization/{personalization => personalization-setup}/shared-session.mdx (100%) rename settings/authentication-personalization/{shared-features.mdx => personalization.mdx} (91%) diff --git a/mint.json b/mint.json index 9cdaef81b..47d66515f 100644 --- a/mint.json +++ b/mint.json @@ -115,25 +115,26 @@ "icon": "user-lock", "group": "Authentication & Personalization", "pages": [ - "settings/authentication-personalization/shared-features", + "settings/authentication-personalization/personalization", + "settings/authentication-personalization/authentication", "settings/authentication-personalization/authentication-vs-personalization", { "group": "Authentication Setup", "pages": [ - "settings/authentication-personalization/authentication/choosing-a-handshake", - "settings/authentication-personalization/authentication/password", - "settings/authentication-personalization/authentication/jwt", - "settings/authentication-personalization/authentication/oauth", - "settings/authentication-personalization/authentication/mintlify" + "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/choosing-a-handshake", - "settings/authentication-personalization/personalization/shared-session", - "settings/authentication-personalization/personalization/jwt", - "settings/authentication-personalization/personalization/oauth" + "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" diff --git a/settings/authentication-personalization/authentication/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx similarity index 96% rename from settings/authentication-personalization/authentication/choosing-a-handshake.mdx rename to settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx index 19fc1c360..1c0224dd9 100644 --- a/settings/authentication-personalization/authentication/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx @@ -4,7 +4,7 @@ description: 'How to decide which auth method is right for your docs' --- - This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization/choosing-a-handshake). + This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization-setup/choosing-a-handshake). Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods: diff --git a/settings/authentication-personalization/authentication/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx similarity index 97% rename from settings/authentication-personalization/authentication/jwt.mdx rename to settings/authentication-personalization/authentication-setup/jwt.mdx index 963c4dead..00c3dd475 100644 --- a/settings/authentication-personalization/authentication/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -4,7 +4,7 @@ description: 'Use a customized login flow to authenticate users' --- - This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization/jwt) are slightly different. + 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. 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. diff --git a/settings/authentication-personalization/authentication/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx similarity index 100% rename from settings/authentication-personalization/authentication/mintlify.mdx rename to settings/authentication-personalization/authentication-setup/mintlify.mdx diff --git a/settings/authentication-personalization/authentication/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx similarity index 98% rename from settings/authentication-personalization/authentication/oauth.mdx rename to settings/authentication-personalization/authentication-setup/oauth.mdx index 083abc0a7..2bdaefbfc 100644 --- a/settings/authentication-personalization/authentication/oauth.mdx +++ b/settings/authentication-personalization/authentication-setup/oauth.mdx @@ -4,7 +4,7 @@ description: 'Integrate with your OAuth server to enable user login via the PKCE --- - 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. + 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. If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience. diff --git a/settings/authentication-personalization/authentication/password.mdx b/settings/authentication-personalization/authentication-setup/password.mdx similarity index 100% rename from settings/authentication-personalization/authentication/password.mdx rename to settings/authentication-personalization/authentication-setup/password.mdx diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx new file mode 100644 index 000000000..691ff65ce --- /dev/null +++ b/settings/authentication-personalization/authentication.mdx @@ -0,0 +1,17 @@ +--- +title: 'Authentication' +description: 'Features available with the Authentication product' +--- + +Authentication can be thought of as Personalization + privacy. All features +that are available via Personalization are also available via Authentication. +For more information about the features of Personalization, +[visit our docs on Personalization](./personalization). + +As the name suggests, Authentication offers full privacy for all of your +documentation content. This includes all of the following: + +- Documentation page content +- Images used in documentation pages +- Search results +- AI chat interactions diff --git a/settings/authentication-personalization/personalization/choosing-a-handshake.mdx b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx similarity index 97% rename from settings/authentication-personalization/personalization/choosing-a-handshake.mdx rename to settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx index 4f65f2367..90fec6157 100644 --- a/settings/authentication-personalization/personalization/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx @@ -4,7 +4,7 @@ description: 'How to decide which auth method is right for your docs' --- - This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication/choosing-a-handshake). + This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication-setup/choosing-a-handshake). Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods: diff --git a/settings/authentication-personalization/personalization/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx similarity index 97% rename from settings/authentication-personalization/personalization/jwt.mdx rename to settings/authentication-personalization/personalization-setup/jwt.mdx index e4e599f3e..ea485ef2b 100644 --- a/settings/authentication-personalization/personalization/jwt.mdx +++ b/settings/authentication-personalization/personalization-setup/jwt.mdx @@ -4,7 +4,7 @@ description: 'Use a customized login flow to authenticate users' --- - This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication/jwt) are slightly different. + This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/jwt) are slightly different. diff --git a/settings/authentication-personalization/personalization/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx similarity index 98% rename from settings/authentication-personalization/personalization/oauth.mdx rename to settings/authentication-personalization/personalization-setup/oauth.mdx index 09da1a4f6..d7cfba89c 100644 --- a/settings/authentication-personalization/personalization/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -4,7 +4,7 @@ description: 'Integrate with your OAuth server to enable user login via the PKCE --- - This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication/oauth) are slightly different. + This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different. If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. diff --git a/settings/authentication-personalization/personalization/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx similarity index 100% rename from settings/authentication-personalization/personalization/shared-session.mdx rename to settings/authentication-personalization/personalization-setup/shared-session.mdx diff --git a/settings/authentication-personalization/shared-features.mdx b/settings/authentication-personalization/personalization.mdx similarity index 91% rename from settings/authentication-personalization/shared-features.mdx rename to settings/authentication-personalization/personalization.mdx index 7349c70bc..972a35fb7 100644 --- a/settings/authentication-personalization/shared-features.mdx +++ b/settings/authentication-personalization/personalization.mdx @@ -1,15 +1,11 @@ --- -title: 'Shared Features' -description: 'A list of features offered by both Authentication and Personalization' +title: 'Personalization' +description: 'A list of features unlocked with Personalization' --- Personalization refers to a suite of features that allow you to customize your -documentation experience based on some information about the user. Authentication -can be thought of as Personalization + privacy. - -This page will explain the different features of Personalization, all of which -are also available with Authentication. There are three major features of -Personalization: +documentation experience based on some information about the user. There are +three major features of Personalization: - **Customize MDX content** with a user's information, such as their name, plan, or title. From a36e3f627da350125ac02becff8026655230625c Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:03:41 -0800 Subject: [PATCH 07/17] shorten group title --- mint.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mint.json b/mint.json index 47d66515f..a50726fdc 100644 --- a/mint.json +++ b/mint.json @@ -113,7 +113,7 @@ "pages": [ { "icon": "user-lock", - "group": "Authentication & Personalization", + "group": "Auth & Personalization", "pages": [ "settings/authentication-personalization/personalization", "settings/authentication-personalization/authentication", From af641ad1d28c4c337ebb871ba961fbd37b6bed88 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:17:34 -0800 Subject: [PATCH 08/17] update all references to user auth --- changelog/overview.mdx | 2 +- .../authentication-setup/jwt.mdx | 4 ++-- .../authentication-setup/mintlify.mdx | 2 +- .../authentication-setup/oauth.mdx | 4 ++-- .../personalization-setup/jwt.mdx | 4 ++-- .../personalization-setup/oauth.mdx | 4 ++-- .../personalization-setup/shared-session.mdx | 4 ++-- settings/authentication-personalization/personalization.mdx | 6 +++--- 8 files changed, 15 insertions(+), 15 deletions(-) diff --git a/changelog/overview.mdx b/changelog/overview.mdx index 22d83458a..2ab381bac 100644 --- a/changelog/overview.mdx +++ b/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 diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index 00c3dd475..83528cea5 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -22,8 +22,8 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - 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 - - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your User Auth settings. + + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your Authentication settings. diff --git a/settings/authentication-personalization/authentication-setup/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx index f9c192c12..9edaadcd2 100644 --- a/settings/authentication-personalization/authentication-setup/mintlify.mdx +++ b/settings/authentication-personalization/authentication-setup/mintlify.mdx @@ -13,7 +13,7 @@ your dashboard will automatically be able to access your documentation. ## Implementation - + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and enable the Mintlify Dashboard Handshake. diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx index 2bdaefbfc..12e48b126 100644 --- a/settings/authentication-personalization/authentication-setup/oauth.mdx +++ b/settings/authentication-personalization/authentication-setup/oauth.mdx @@ -12,7 +12,7 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam ## Implementation - + 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. @@ -39,7 +39,7 @@ I have an existing OAuth server that supports the PKCE flow. I want to set up au 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 User Auth settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: +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']` diff --git a/settings/authentication-personalization/personalization-setup/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx index ea485ef2b..9a46de71a 100644 --- a/settings/authentication-personalization/personalization-setup/jwt.mdx +++ b/settings/authentication-personalization/personalization-setup/jwt.mdx @@ -23,8 +23,8 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - 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 - - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your User Auth settings. + + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your Personalization settings. diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index d7cfba89c..30b6c637c 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -15,7 +15,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr 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. Take note of the scope or scopes required to access this endpoint. - + Go to your [Mintlify dashboard 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. @@ -35,7 +35,7 @@ I have an existing OAuth server that supports the PKCE flow. I want to set up au 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 User Auth settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: +I then go to the Mintlify dashboard settings, navigate to the Personalization 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']` diff --git a/settings/authentication-personalization/personalization-setup/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx index aaf7d4578..1e7da98ab 100644 --- a/settings/authentication-personalization/personalization-setup/shared-session.mdx +++ b/settings/authentication-personalization/personalization-setup/shared-session.mdx @@ -22,8 +22,8 @@ This method utilizes the session authentication info already stored in your user These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints. - - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the API URL and your Login URL to your User Auth settings. + + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the API URL and your Login URL to your Personalization settings. diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx index 972a35fb7..531bd62ea 100644 --- a/settings/authentication-personalization/personalization.mdx +++ b/settings/authentication-personalization/personalization.mdx @@ -25,9 +25,9 @@ Hello, {userContext.name ?? 'reader'}! Hello, {userContext.name ?? 'reader'}! ``` -This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer's existing plan: +This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan: -User Auth is an enterprise feature. { +Personalization is an enterprise feature. { userContext.org === undefined ? <>To access this feature, first create an account at the Mintlify dashboard. : userContext.org.plan !== 'enterprise' @@ -36,7 +36,7 @@ userContext.org === undefined } ```jsx -User Auth is an enterprise feature. { +Personalization is an enterprise feature. { userContext.org === undefined ? <>To access this feature, first create an account at the Mintlify dashboard. : userContext.org.plan !== 'enterprise' From aa5f97785eed204a9326d70f09888521ea4d3145 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:21:30 -0800 Subject: [PATCH 09/17] update order of auth/personalization docs --- mint.json | 2 +- .../authentication-personalization/authentication.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/mint.json b/mint.json index a50726fdc..59a4fd2d8 100644 --- a/mint.json +++ b/mint.json @@ -115,8 +115,8 @@ "icon": "user-lock", "group": "Auth & Personalization", "pages": [ - "settings/authentication-personalization/personalization", "settings/authentication-personalization/authentication", + "settings/authentication-personalization/personalization", "settings/authentication-personalization/authentication-vs-personalization", { "group": "Authentication Setup", diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx index 691ff65ce..8e143c835 100644 --- a/settings/authentication-personalization/authentication.mdx +++ b/settings/authentication-personalization/authentication.mdx @@ -3,11 +3,6 @@ title: 'Authentication' description: 'Features available with the Authentication product' --- -Authentication can be thought of as Personalization + privacy. All features -that are available via Personalization are also available via Authentication. -For more information about the features of Personalization, -[visit our docs on Personalization](./personalization). - As the name suggests, Authentication offers full privacy for all of your documentation content. This includes all of the following: @@ -15,3 +10,8 @@ documentation content. This includes all of the following: - Images used in documentation pages - Search results - AI chat interactions + +Authentication can be thought of as Personalization + privacy. In addition +to securing your documentation content, all features that are available via +Personalization are also available via Authentication. For more information +about the features of Personalization, [visit our docs on Personalization](./personalization). From 4e79f9396023feed1a5c3ad5d2bba48749a303b1 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:24:33 -0800 Subject: [PATCH 10/17] add enterprise feature callout --- settings/authentication-personalization/authentication.mdx | 4 ++++ settings/authentication-personalization/personalization.mdx | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx index 8e143c835..b645e1fb5 100644 --- a/settings/authentication-personalization/authentication.mdx +++ b/settings/authentication-personalization/authentication.mdx @@ -3,6 +3,10 @@ title: 'Authentication' description: 'Features available with the Authentication product' --- + + Authentication is an enterprise feature. To get access, [contact sales](mailto:sales@mintlify.com). + + As the name suggests, Authentication offers full privacy for all of your documentation content. This includes all of the following: diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx index 531bd62ea..37c4af910 100644 --- a/settings/authentication-personalization/personalization.mdx +++ b/settings/authentication-personalization/personalization.mdx @@ -3,6 +3,10 @@ title: 'Personalization' description: 'A list of features unlocked with Personalization' --- + + Personalization is an enterprise feature. To get access, [contact sales](mailto:sales@mintlify.com). + + Personalization refers to a suite of features that allow you to customize your documentation experience based on some information about the user. There are three major features of Personalization: From cc409f4759388b0f4871d340f262f05676c331bc Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:27:51 -0800 Subject: [PATCH 11/17] title/description nits --- .../authentication-vs-personalization.mdx | 2 +- settings/authentication-personalization/sending-data.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/settings/authentication-personalization/authentication-vs-personalization.mdx b/settings/authentication-personalization/authentication-vs-personalization.mdx index 4b0dd5a54..e48fbef9a 100644 --- a/settings/authentication-personalization/authentication-vs-personalization.mdx +++ b/settings/authentication-personalization/authentication-vs-personalization.mdx @@ -1,5 +1,5 @@ --- -title: 'Authentication vs Personalization' +title: 'Auth vs Personalization' description: 'How to determine which product is best for you' --- diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index c5a685446..bb7b17d17 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -1,6 +1,6 @@ --- title: 'Sending Data' -description: 'The types and shape of user data you can send to Mintlify' +description: 'The shape of user data you can use to personalize your docs' --- Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both: From cdc02d96b523f28fe41a896fd742623080a4bad6 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:28:44 -0800 Subject: [PATCH 12/17] delete comment --- .../authentication-vs-personalization.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/settings/authentication-personalization/authentication-vs-personalization.mdx b/settings/authentication-personalization/authentication-vs-personalization.mdx index e48fbef9a..25e1221ae 100644 --- a/settings/authentication-personalization/authentication-vs-personalization.mdx +++ b/settings/authentication-personalization/authentication-vs-personalization.mdx @@ -35,12 +35,3 @@ Personalization offers one additional Handshake method: - **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint that returns data for already-authenticated users. - -{/* -### Pricing - -Mintlify strives to ensure that your private content stays private, full stop. Because this level -of security is not easy to achieve, Authentication is an enterprise feature. If an enterprise plan -doesn't make sense for you, consider whether Personalization might meet your needs. Personalization -is available on all plans. -*/} From b559dbb60c2ad16c483e7a70a5a9f5dd7764e3eb Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:29:52 -0800 Subject: [PATCH 13/17] update oauth info for authentication --- .../authentication-setup/choosing-a-handshake.mdx | 2 +- .../authentication-setup/oauth.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx index 1c0224dd9..e8a27e11b 100644 --- a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx @@ -28,7 +28,7 @@ Before your users can access personalized content, they must be authenticated. M - - You have an existing OAuth server that supports the PKCE flow. + - You have an existing OAuth server that supports the Authorization Code flow. - You can create a new API endpoint that can be accessed by the returned OAuth access token. diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx index 12e48b126..19ae39de0 100644 --- a/settings/authentication-personalization/authentication-setup/oauth.mdx +++ b/settings/authentication-personalization/authentication-setup/oauth.mdx @@ -1,6 +1,6 @@ --- title: 'OAuth 2.0 Handshake' -description: 'Integrate with your OAuth server to enable user login via the PKCE flow' +description: 'Integrate with your OAuth server to enable user login via the Authorization Code flow' --- @@ -35,7 +35,7 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam ## 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`. +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`. 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. From 3226531537bdfe6f38abededd557c60c0e1c0b05 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:38:54 -0800 Subject: [PATCH 14/17] udpate mintlify handshake description --- .../authentication-setup/mintlify.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/authentication-personalization/authentication-setup/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx index 9edaadcd2..e9430171d 100644 --- a/settings/authentication-personalization/authentication-setup/mintlify.mdx +++ b/settings/authentication-personalization/authentication-setup/mintlify.mdx @@ -1,6 +1,6 @@ --- title: 'Mintlify Dashboard Handshake' -description: 'Use a customized login flow to authenticate users' +description: 'Use the Mintlify Dashboard to authenticate users' --- From 15a4c20b9774b0b85ab2b444c4ec8d00716913d5 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:44:49 -0800 Subject: [PATCH 15/17] update mintlify dashboard links --- .../authentication-setup/jwt.mdx | 4 ++-- .../authentication-setup/mintlify.mdx | 8 ++++---- .../authentication-setup/oauth.mdx | 6 +++--- .../authentication-setup/password.mdx | 2 +- .../personalization-setup/jwt.mdx | 4 ++-- .../personalization-setup/oauth.mdx | 4 ++-- .../personalization-setup/shared-session.mdx | 2 +- settings/gitlab.mdx | 2 +- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index 83528cea5..b5d5dd5f8 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -13,7 +13,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - 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. + 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. Create a login flow that does the following: @@ -23,7 +23,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - Create a redirect URL back to your docs, including the JWT as the hash - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your Authentication settings. + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings. diff --git a/settings/authentication-personalization/authentication-setup/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx index e9430171d..0ed517c96 100644 --- a/settings/authentication-personalization/authentication-setup/mintlify.mdx +++ b/settings/authentication-personalization/authentication-setup/mintlify.mdx @@ -14,11 +14,11 @@ your dashboard will automatically be able to access your documentation. - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and enable the Mintlify Dashboard Handshake. + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and enable the Mintlify Dashboard Handshake. 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). + [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members). @@ -28,8 +28,8 @@ I want to set up authentication for my docs hosted at `docs.foo.com`. I want my 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) +To set up authentication with Mintlify, I go to my [Mintlify dashboard settings](https://dashboard.mintlify.com/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). +my [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members). diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx index 19ae39de0..bd90afae4 100644 --- a/settings/authentication-personalization/authentication-setup/oauth.mdx +++ b/settings/authentication-personalization/authentication-setup/oauth.mdx @@ -13,7 +13,7 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam - Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication), select the OAuth option, and fill out the required fields: + Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/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. @@ -22,13 +22,13 @@ If you have an existing OAuth server, you can integrate with Mintlify for a seam - **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. - 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. + 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. 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 + Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL to your OAuth configuration. diff --git a/settings/authentication-personalization/authentication-setup/password.mdx b/settings/authentication-personalization/authentication-setup/password.mdx index 6f8ed9a2d..2ce275cc8 100644 --- a/settings/authentication-personalization/authentication-setup/password.mdx +++ b/settings/authentication-personalization/authentication-setup/password.mdx @@ -15,7 +15,7 @@ protect your docs. - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and create a password. + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and create a password. Securely share the password with your documentation readers. That's it! diff --git a/settings/authentication-personalization/personalization-setup/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx index 9a46de71a..7d2b4470e 100644 --- a/settings/authentication-personalization/personalization-setup/jwt.mdx +++ b/settings/authentication-personalization/personalization-setup/jwt.mdx @@ -14,7 +14,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - 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. + 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. Create a login flow that does the following: @@ -24,7 +24,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - Create a redirect URL back to your docs, including the JWT as the hash - Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the login URL to your Personalization settings. + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Personalization settings. diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index 30b6c637c..b90859f9b 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -16,7 +16,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr 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. Take note of the scope or scopes required to access this endpoint. - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication), select the OAuth option, and fill out the required fields: + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/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. @@ -25,7 +25,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr - **Info API URL**: The endpoint that will be hit to retrieve user info. - Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add it as an authorized redirect URL for your OAuth server. + Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server. diff --git a/settings/authentication-personalization/personalization-setup/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx index 1e7da98ab..a73aa0a83 100644 --- a/settings/authentication-personalization/personalization-setup/shared-session.mdx +++ b/settings/authentication-personalization/personalization-setup/shared-session.mdx @@ -23,7 +23,7 @@ This method utilizes the session authentication info already stored in your user - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/products/authentication) and add the API URL and your Login URL to your Personalization settings. + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the API URL and your Login URL to your Personalization settings. diff --git a/settings/gitlab.mdx b/settings/gitlab.mdx index 576ba17f2..94163087b 100644 --- a/settings/gitlab.mdx +++ b/settings/gitlab.mdx @@ -41,7 +41,7 @@ changes between GitLab and Mintlify. - Within the [Mintlify dashboard](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/git-settings), add the project ID and access token from the previous steps alongside the other configurations. Click "Save Changes" when you're done. + Within the [Mintlify dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings), add the project ID and access token from the previous steps alongside the other configurations. Click "Save Changes" when you're done. From b7841e20656fb8f49f3c132f5cc50781f8079fc2 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 16:06:24 -0800 Subject: [PATCH 16/17] fix jwt code --- .../authentication-setup/jwt.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx index b5d5dd5f8..16d6f59eb 100644 --- a/settings/authentication-personalization/authentication-setup/jwt.mdx +++ b/settings/authentication-personalization/authentication-setup/jwt.mdx @@ -20,7 +20,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs - 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 + - Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings. @@ -45,7 +45,7 @@ Login URL field. Here's what the code might look like: -```ts +```ts TypeScript import * as jose from 'jose'; import { Request, Response } from 'express'; @@ -68,11 +68,11 @@ export async function handleRequest(req: Request, res: Response) { .setExpirationTime('10 s') // 10 second JWT expiration .sign(signingKey); - return res.redirect(`https://docs.foo.com#${jwt}`); + return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); } ``` -```python +```python Python import jwt # pyjwt import os From a861a53261022809149ac40c96276de78ac67cc0 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Tue, 10 Dec 2024 16:09:04 -0800 Subject: [PATCH 17/17] updat eauth method copy --- .../authentication-setup/choosing-a-handshake.mdx | 2 +- .../personalization-setup/choosing-a-handshake.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx index e8a27e11b..c3f7afd6e 100644 --- a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx @@ -1,6 +1,6 @@ --- title: 'Choosing a Handshake' -description: 'How to decide which auth method is right for your docs' +description: 'How to decide which Handshake method is right for your docs' --- diff --git a/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx index 90fec6157..9c7823cc3 100644 --- a/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx +++ b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx @@ -1,6 +1,6 @@ --- title: 'Choosing a Handshake' -description: 'How to decide which auth method is right for your docs' +description: 'How to decide which Handshake method is right for your docs' ---