From 25acf7e5862048831641e7b0106a1b67dcd98289 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:12:52 +0000 Subject: [PATCH 01/16] Documentation edits made through Mintlify web editor --- integrations/user-auth/introduction.mdx | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 integrations/user-auth/introduction.mdx diff --git a/integrations/user-auth/introduction.mdx b/integrations/user-auth/introduction.mdx new file mode 100644 index 000000000..f6ad53aea --- /dev/null +++ b/integrations/user-auth/introduction.mdx @@ -0,0 +1,5 @@ +--- +title: 'User Auth' +description: 'Give your users a personalized docs experience' +--- + From aa578df1e65534019a820c1dce5e490084d28c59 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:15:40 +0000 Subject: [PATCH 02/16] Documentation edits made through Mintlify web editor From cb571731efb24999cfabf0cb6b4203be9462f69a Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:28:42 +0000 Subject: [PATCH 03/16] Documentation edits made through Mintlify web editor --- integrations/user-auth/introduction.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/integrations/user-auth/introduction.mdx b/integrations/user-auth/introduction.mdx index f6ad53aea..3f6cbd502 100644 --- a/integrations/user-auth/introduction.mdx +++ b/integrations/user-auth/introduction.mdx @@ -3,3 +3,21 @@ title: 'User Auth' description: 'Give your users a personalized docs experience' --- +Sometimes, when writing docs, you wish you knew just a little bit about the person reading them. Maybe you only want to show them the information they should care about. Maybe you want to craft examples that they could use out-of-the-box. + +With Mintlify, you can add User Auth to identify your users and tailor your docs content to them. + +## What is User Auth + +User auth will allow better customization of the docs, enabling the following features: + +1. Customizing MDX content with the user's information, such as their name, title, or payment plan. +2. Injecting user API keys into the API Playground. +3. Hiding/showing pages in the navigation based on user groups. + +## What *isn't* User Auth + +At this time, User Auth cannot provide any of the following: + +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. From 5769cad072dfe0bd787efb6f015132f92f6c530c Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:29:19 +0000 Subject: [PATCH 04/16] Documentation edits made through Mintlify web editor From 848bfc7614d94a0e84f53806f2665816255cffd6 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:31:58 +0000 Subject: [PATCH 05/16] Documentation edits made through Mintlify web editor From ee9ecc114e6ab6c5d7fdc2de77048c97b298a0f6 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:16:59 -0700 Subject: [PATCH 06/16] improve overview info --- integrations/user-auth/introduction.mdx | 23 ----------------------- integrations/user-auth/overview.mdx | 23 +++++++++++++++++++++++ 2 files changed, 23 insertions(+), 23 deletions(-) delete mode 100644 integrations/user-auth/introduction.mdx create mode 100644 integrations/user-auth/overview.mdx diff --git a/integrations/user-auth/introduction.mdx b/integrations/user-auth/introduction.mdx deleted file mode 100644 index 3f6cbd502..000000000 --- a/integrations/user-auth/introduction.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 'User Auth' -description: 'Give your users a personalized docs experience' ---- - -Sometimes, when writing docs, you wish you knew just a little bit about the person reading them. Maybe you only want to show them the information they should care about. Maybe you want to craft examples that they could use out-of-the-box. - -With Mintlify, you can add User Auth to identify your users and tailor your docs content to them. - -## What is User Auth - -User auth will allow better customization of the docs, enabling the following features: - -1. Customizing MDX content with the user's information, such as their name, title, or payment plan. -2. Injecting user API keys into the API Playground. -3. Hiding/showing pages in the navigation based on user groups. - -## What *isn't* User Auth - -At this time, User Auth cannot provide any of the following: - -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. diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx new file mode 100644 index 000000000..07171ac7e --- /dev/null +++ b/integrations/user-auth/overview.mdx @@ -0,0 +1,23 @@ +--- +title: 'Overview' +description: 'Give your users a personalized docs experience' +--- + +Sometimes, when writing docs, you wish you knew just a little bit about the person reading them. Maybe you only want to show them the information they should care about. Maybe you want to craft examples that they can use out-of-the-box. + +With Mintlify, you can add User Auth to identify your users and tailor your docs content to them. + +## What is User Auth + +User Auth allows you to configure a method for identifying and authenticating your users. Once authenticated, you can share user-specific information that can be used to personalize the docs. This unlocks some powerful features: + +1. **Customizing MDX content** with a user's information, such as their title or plan. +2. **Prefilling API keys** in the API Playground for streamlined use. +3. **Selectively showing pages** in the navigation based on a user's groups. + +## What *isn't* User Auth + +At this time, User Auth cannot provide any of the following: + +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. From 7ad28048b42819e2dd1d1cf8875f102bea421991 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Fri, 21 Jun 2024 21:48:21 -0700 Subject: [PATCH 07/16] add docs for shared session --- integrations/user-auth/overview.mdx | 6 +- integrations/user-auth/shared-session.mdx | 74 +++++++++++++++++++++++ 2 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 integrations/user-auth/shared-session.mdx diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index 07171ac7e..bb65f39a7 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -11,9 +11,9 @@ With Mintlify, you can add User Auth to identify your users and tailor your docs User Auth allows you to configure a method for identifying and authenticating your users. Once authenticated, you can share user-specific information that can be used to personalize the docs. This unlocks some powerful features: -1. **Customizing MDX content** with a user's information, such as their title or plan. -2. **Prefilling API keys** in the API Playground for streamlined use. -3. **Selectively showing pages** in the navigation based on a user's groups. +1. **Customize MDX content** with a user's information, such as their title or plan. +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 diff --git a/integrations/user-auth/shared-session.mdx b/integrations/user-auth/shared-session.mdx new file mode 100644 index 000000000..d708c23ed --- /dev/null +++ b/integrations/user-auth/shared-session.mdx @@ -0,0 +1,74 @@ +--- +title: 'Shared Session' +description: 'Seamlessly share user sessions between your dashboard and your docs' +--- + +This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. + +## Prerequisites + +- You have a dashboard or other user portal hosted at your domain. +- Your users' session credentials are stored as cookies. +- You can create a new API endpoint at the same origin or a subdomain of your dashboard + - If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com` + - If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com` +- Your docs are hosted at the same domain as your dashboard. + - If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` + - If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` + +## Implementation requirements + + + + Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload of the format prescribed by Mintlify + + 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 `*`) + - Ensure your API’s `Access-Control-Allow-Credentials` header is `true` + + 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/settings/integrations) and add the API URL and your Login URL to your User Auth settings. + + + +## Pros & Cons + +Pros: + +- Users that are logged into your dashboard are automatically logged into your docs +- Persistent user session +- Refresh data without requiring additional login +- Minimal setup required + +Cons: + +- Your docs will make a request to your backend, which may be undesirable + +## Examples + +### Dashboard at subdomain, docs at subdomain + +I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`. + +To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**. + +I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. + +### Dashboard at subdomain, docs at root + +I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`. + +To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**. + +I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field. + +### Dashboard at root, docs at root + +I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`. + +To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. + +I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field. \ No newline at end of file From da8ab1779ffa92dafe61a71116b5b99851f49392 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Fri, 21 Jun 2024 22:12:01 -0700 Subject: [PATCH 08/16] add jwt docs --- integrations/user-auth/jwt.mdx | 52 +++++++++++++++++++++++ integrations/user-auth/shared-session.mdx | 4 +- mint.json | 8 ++++ 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 integrations/user-auth/jwt.mdx diff --git a/integrations/user-auth/jwt.mdx b/integrations/user-auth/jwt.mdx new file mode 100644 index 000000000..a7807fdc6 --- /dev/null +++ b/integrations/user-auth/jwt.mdx @@ -0,0 +1,52 @@ +--- +title: 'JWT Auth' +description: 'Use a customized login flow to authenticate users' +--- + +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. + +## Prerequisites + +- None + +## Implementation + + + + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/integrations) 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 format prescribed by Mintlify + - Sign the JWT with the secret + - Create a redirect URL back to your docs, including the JWT as a query parameter with the name `user_auth` + + + Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/integrations) and add the login URL to your User Auth settings. + + + +## Pros & Cons + +Pros: + +- No dashboard needed +- Small amount of setup required +- Reduced risk of API endpoint abuse +- Zero additional CORS configuration + +Cons: + +- Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately +- Every time you want to refresh user data, your users must re-login to your docs + - If your users' data changes frequently, you must require your users to log in frequently or risk having stale data in the docs + - If your users' data rarely changes, this shouldn't be a problem + +## 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 sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com?user_auth={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. \ No newline at end of file diff --git a/integrations/user-auth/shared-session.mdx b/integrations/user-auth/shared-session.mdx index d708c23ed..82902c6c2 100644 --- a/integrations/user-auth/shared-session.mdx +++ b/integrations/user-auth/shared-session.mdx @@ -1,5 +1,5 @@ --- -title: 'Shared Session' +title: 'Shared Session Auth' description: 'Seamlessly share user sessions between your dashboard and your docs' --- @@ -16,7 +16,7 @@ This method utilizes the session authentication info already stored in your user - If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` - If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` -## Implementation requirements +## Implementation diff --git a/mint.json b/mint.json index 626959a65..a653848f8 100644 --- a/mint.json +++ b/mint.json @@ -146,6 +146,14 @@ "group": "SDKs", "pages": ["integrations/sdks/speakeasy", "integrations/sdks/stainless"] }, + { + "group": "User Auth", + "pages": [ + "integrations/user-auth/overview", + "integrations/user-auth/shared-session", + "integrations/user-auth/jwt" + ] + }, { "group": "Components", "pages": [ From bb226418f1cedd1ba17425cba8b6e358d2ab7de4 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Sat, 22 Jun 2024 01:58:35 -0700 Subject: [PATCH 09/16] add docs on shape of data --- integrations/user-auth/user-info.mdx | 50 ++++++++++++++++++++++++++++ mint.json | 1 + 2 files changed, 51 insertions(+) create mode 100644 integrations/user-auth/user-info.mdx diff --git a/integrations/user-auth/user-info.mdx b/integrations/user-auth/user-info.mdx new file mode 100644 index 000000000..1831f2d70 --- /dev/null +++ b/integrations/user-auth/user-info.mdx @@ -0,0 +1,50 @@ +--- +title: 'User Info' +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 all: + +```tsx +{ + expiresAt?: number; + groups?: string[]; + content?: Record; + apiPlaygroundInputs?: { + header?: Record; + query?: Record; + cookie?: Record; + server?: Record; + }; +} +``` + + + 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 customers using JWT Auth:** This is *not* the same as the `exp` claim of the JWT. The `expiresAt` field determines when retrieved data should be considered stale. The `exp` claim determines when a JWT is no longer valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. + + + A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown. + + + A bag of values that can be accessed from within MDX content using the `userContext` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {userContext.firstName}!` + + + User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'mintlify' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. + + The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section. + + + \ No newline at end of file diff --git a/mint.json b/mint.json index a653848f8..1dbbe0f5d 100644 --- a/mint.json +++ b/mint.json @@ -150,6 +150,7 @@ "group": "User Auth", "pages": [ "integrations/user-auth/overview", + "integrations/user-auth/user-info", "integrations/user-auth/shared-session", "integrations/user-auth/jwt" ] From 901a5be4f1c00a9eb1893f3fc6dbe6e434816797 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Sat, 22 Jun 2024 12:27:36 -0700 Subject: [PATCH 10/16] add usage docs --- integrations/user-auth/jwt.mdx | 4 +- integrations/user-auth/overview.mdx | 56 +++++++++++++++++++++++ integrations/user-auth/shared-session.mdx | 4 +- integrations/user-auth/user-info.mdx | 6 +-- 4 files changed, 63 insertions(+), 7 deletions(-) diff --git a/integrations/user-auth/jwt.mdx b/integrations/user-auth/jwt.mdx index a7807fdc6..b2e88eb69 100644 --- a/integrations/user-auth/jwt.mdx +++ b/integrations/user-auth/jwt.mdx @@ -7,7 +7,7 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs ## Prerequisites -- None +None ## Implementation @@ -18,7 +18,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 format prescribed by Mintlify + - Create a JWT containing the authenticated user's info in the [User Info](./user-info) shape prescribed by Mintlify - Sign the JWT with the secret - Create a redirect URL back to your docs, including the JWT as a query parameter with the name `user_auth` diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index bb65f39a7..6747822ae 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -21,3 +21,59 @@ At this time, User Auth cannot provide any of the following: 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. + +## 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 real world example: + +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 upgrade, navigate to the billing page in the Mintlify dashboard. + : <>As an enterprise organization, you can enable this feature right now from your Mintlify dashboard settings +} + +```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 upgrade, navigate to the billing page in the Mintlify dashboard. + : <>As an enterprise organization, you can enable this feature right now from your Mintlify dashboard settings +} +``` + + + 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 page 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 your 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 User Info and page metadata: + +| | `groups` not in User Info | `groups: []` in User Info | `groups: ['admin']` in User Info | +|:-----------------------------------|:------------------------:|:-------------------------:|:--------------------------------:| +| `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." diff --git a/integrations/user-auth/shared-session.mdx b/integrations/user-auth/shared-session.mdx index 82902c6c2..e0833b8bf 100644 --- a/integrations/user-auth/shared-session.mdx +++ b/integrations/user-auth/shared-session.mdx @@ -9,7 +9,7 @@ This method utilizes the session authentication info already stored in your user - You have a dashboard or other user portal hosted at your domain. - Your users' session credentials are stored as cookies. -- You can create a new API endpoint at the same origin or a subdomain of your dashboard +- You can create a new API endpoint at the same origin or a subdomain of your dashboard. - If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com` - If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com` - Your docs are hosted at the same domain as your dashboard. @@ -20,7 +20,7 @@ This method utilizes the session authentication info already stored in your user - Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload of the format prescribed by Mintlify + Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [User Info](./user-info) format prescribed by Mintlify. 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 `*`) diff --git a/integrations/user-auth/user-info.mdx b/integrations/user-auth/user-info.mdx index 1831f2d70..1f19e93e5 100644 --- a/integrations/user-auth/user-info.mdx +++ b/integrations/user-auth/user-info.mdx @@ -16,7 +16,7 @@ Depending on your authentication configuration, your API will respond with eithe cookie?: Record; server?: Record; }; -} +}; ``` 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 customers using JWT Auth:** This is *not* the same as the `exp` claim of the JWT. The `expiresAt` field determines when retrieved data should be considered stale. The `exp` claim determines when a JWT is no longer valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. + 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. - User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'mintlify' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. + User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section. From 0fc12c21dad94ab19268f32fcc836eee21d55c65 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Sat, 22 Jun 2024 12:30:18 -0700 Subject: [PATCH 11/16] remove unnecessary optionals --- integrations/user-auth/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index 6747822ae..99fe5776e 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -32,7 +32,7 @@ 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 upgrade, navigate to the billing page in the Mintlify dashboard. + ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To upgrade, navigate to the billing page in the Mintlify dashboard. : <>As an enterprise organization, you can enable this feature right now from your Mintlify dashboard settings } @@ -41,13 +41,13 @@ 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 upgrade, navigate to the billing page in the Mintlify dashboard. + ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To upgrade, navigate to the billing page in the Mintlify dashboard. : <>As an enterprise organization, you can enable this feature right now from your Mintlify dashboard settings } ``` - 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 page crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}` + 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 From 3bc8db1249526050082a06c66ff67c9997ddfbed Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Sat, 22 Jun 2024 12:39:56 -0700 Subject: [PATCH 12/16] hide hidden pages docs since it's not out yet --- integrations/user-auth/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index 99fe5776e..31d5720b2 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -13,7 +13,7 @@ User Auth allows you to configure a method for identifying and authenticating yo 1. **Customize MDX content** with a user's information, such as their title or plan. 2. **Prefill API keys** in the API Playground for streamlined use. -3. **Selectively show pages** in the navigation based on a user's groups. +3. (Coming soon!) **Selectively show pages** in the navigation based on a user's groups. ## What *isn't* User Auth @@ -53,7 +53,7 @@ User Auth is an enterprise feature. { ### Prefilling API Keys If you return API Playground inputs in your 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. @@ -76,4 +76,4 @@ Here's a table that displays whether a page is shown for different combinations | `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." +Note that an empty array in the page metadata is interpreted as "No groups should see this page." */} From ca1418c8804c0e927bc01c33077c9f26e79186a3 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Mon, 24 Jun 2024 16:11:12 -0700 Subject: [PATCH 13/16] address comments --- .../user-auth/choosing-an-auth-method.mdx | 59 +++++++++++++++++++ integrations/user-auth/jwt.mdx | 24 +------- integrations/user-auth/overview.mdx | 8 +-- .../{user-info.mdx => sending-data.mdx} | 6 +- integrations/user-auth/shared-session.mdx | 26 +------- mint.json | 12 +++- 6 files changed, 78 insertions(+), 57 deletions(-) create mode 100644 integrations/user-auth/choosing-an-auth-method.mdx rename integrations/user-auth/{user-info.mdx => sending-data.mdx} (97%) diff --git a/integrations/user-auth/choosing-an-auth-method.mdx b/integrations/user-auth/choosing-an-auth-method.mdx new file mode 100644 index 000000000..a4652e6c6 --- /dev/null +++ b/integrations/user-auth/choosing-an-auth-method.mdx @@ -0,0 +1,59 @@ +--- +title: 'Choosing an Auth Method' +description: 'How to decide which auth method is right for your docs' +--- + +Mintlify supports two methods of authenticating users: + +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. + +## Prerequisites + + + + - You have a dashboard or other user portal hosted at your domain. + - Your users' session credentials are stored as cookies. + - You can create a new API endpoint at the same origin or a subdomain of your dashboard. + - If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com` + - If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com` + - Your docs are hosted at the same domain as your dashboard. + - If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` + - If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` + + + - 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. + + + +## Pros & Cons + + + + Pros: + + - Users that are logged into your dashboard are automatically logged into your docs + - Your users' sessions are persistent, meaning you can refresh data without requiring additional login + - Minimal setup required + + Cons: + + - Your docs will make a request to your backend, which may be undesirable + + + Pros: + + - No dashboard needed + - Reduced risk of API endpoint abuse + - Zero CORS configuration + + Cons: + + - Must build new functionality around your existing login flow + - Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately + - Every time you want to refresh user data, your users must re-login to your docs + - If your users' data changes frequently, you must require your users to log in frequently or risk having stale data in the docs + - If your users' data rarely changes, this shouldn't be a problem + + diff --git a/integrations/user-auth/jwt.mdx b/integrations/user-auth/jwt.mdx index b2e88eb69..8d67a08ef 100644 --- a/integrations/user-auth/jwt.mdx +++ b/integrations/user-auth/jwt.mdx @@ -5,10 +5,6 @@ description: 'Use a customized login flow to authenticate users' 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. -## Prerequisites - -None - ## Implementation @@ -18,7 +14,7 @@ None Create a login flow that does the following: - Authenticate the user - - Create a JWT containing the authenticated user's info in the [User Info](./user-info) shape prescribed by Mintlify + - Create a JWT containing the authenticated user's info in the [UserInfo](./sending-data) format - Sign the JWT with the secret - Create a redirect URL back to your docs, including the JWT as a query parameter with the name `user_auth` @@ -27,26 +23,10 @@ None -## Pros & Cons - -Pros: - -- No dashboard needed -- Small amount of setup required -- Reduced risk of API endpoint abuse -- Zero additional CORS configuration - -Cons: - -- Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately -- Every time you want to refresh user data, your users must re-login to your docs - - If your users' data changes frequently, you must require your users to log in frequently or risk having stale data in the docs - - If your users' data rarely changes, this shouldn't be a problem - ## 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 sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com?user_auth={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. \ No newline at end of file +I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the Login URL field. diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index 31d5720b2..a43fa92b1 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -11,7 +11,7 @@ With Mintlify, you can add User Auth to identify your users and tailor your docs User Auth allows you to configure a method for identifying and authenticating your users. Once authenticated, you can share user-specific information that can be used to personalize the docs. This unlocks some powerful features: -1. **Customize MDX content** with a user's information, such as their title or plan. +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. (Coming soon!) **Selectively show pages** in the navigation based on a user's groups. @@ -52,7 +52,7 @@ User Auth is an enterprise feature. { ### Prefilling API Keys -If you return API Playground inputs in your 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. +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 @@ -68,9 +68,9 @@ groups: ['admin'] --- ``` -Here's a table that displays whether a page is shown for different combinations of `groups` in User Info and page metadata: +Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata: -| | `groups` not in User Info | `groups: []` in User Info | `groups: ['admin']` in User Info | +| | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo | |:-----------------------------------|:------------------------:|:-------------------------:|:--------------------------------:| | `groups` not in metadata | ✅ | ✅ | ✅ | | `groups: []` in metadata | ❌ | ❌ | ❌ | diff --git a/integrations/user-auth/user-info.mdx b/integrations/user-auth/sending-data.mdx similarity index 97% rename from integrations/user-auth/user-info.mdx rename to integrations/user-auth/sending-data.mdx index 1f19e93e5..019dc0581 100644 --- a/integrations/user-auth/user-info.mdx +++ b/integrations/user-auth/sending-data.mdx @@ -1,12 +1,12 @@ --- -title: 'User Info' +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 all: +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: ```tsx -{ +type UserInfo = { expiresAt?: number; groups?: string[]; content?: Record; diff --git a/integrations/user-auth/shared-session.mdx b/integrations/user-auth/shared-session.mdx index e0833b8bf..a86f8353b 100644 --- a/integrations/user-auth/shared-session.mdx +++ b/integrations/user-auth/shared-session.mdx @@ -5,22 +5,11 @@ description: 'Seamlessly share user sessions between your dashboard and your doc This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience. -## Prerequisites - -- You have a dashboard or other user portal hosted at your domain. -- Your users' session credentials are stored as cookies. -- You can create a new API endpoint at the same origin or a subdomain of your dashboard. - - If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com` - - If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com` -- Your docs are hosted at the same domain as your dashboard. - - If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` - - If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com` - ## Implementation - Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [User Info](./user-info) format prescribed by Mintlify. + 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 `*`) @@ -34,19 +23,6 @@ This method utilizes the session authentication info already stored in your user -## Pros & Cons - -Pros: - -- Users that are logged into your dashboard are automatically logged into your docs -- Persistent user session -- Refresh data without requiring additional login -- Minimal setup required - -Cons: - -- Your docs will make a request to your backend, which may be undesirable - ## Examples ### Dashboard at subdomain, docs at subdomain diff --git a/mint.json b/mint.json index 1dbbe0f5d..5425d78c6 100644 --- a/mint.json +++ b/mint.json @@ -150,9 +150,15 @@ "group": "User Auth", "pages": [ "integrations/user-auth/overview", - "integrations/user-auth/user-info", - "integrations/user-auth/shared-session", - "integrations/user-auth/jwt" + { + "group": "Authenticating", + "pages": [ + "integrations/user-auth/choosing-an-auth-method", + "integrations/user-auth/shared-session", + "integrations/user-auth/jwt" + ] + }, + "integrations/user-auth/sending-data" ] }, { From a7d23c5d090a802529b9acfe364eacf5d197b6b9 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Mon, 24 Jun 2024 16:16:00 -0700 Subject: [PATCH 14/16] add a better intro on the auth method page --- integrations/user-auth/choosing-an-auth-method.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/user-auth/choosing-an-auth-method.mdx b/integrations/user-auth/choosing-an-auth-method.mdx index a4652e6c6..f04c11ffb 100644 --- a/integrations/user-auth/choosing-an-auth-method.mdx +++ b/integrations/user-auth/choosing-an-auth-method.mdx @@ -3,7 +3,7 @@ title: 'Choosing an Auth Method' description: 'How to decide which auth method is right for your docs' --- -Mintlify supports two methods of authenticating users: +Before your users can access their personalized content, they must be authenticated. Mintlify supports two methods of authenticating users: 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. From 6abd617cd8454f82fe98c50b0e829c12bcbf514a Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Mon, 24 Jun 2024 16:19:08 -0700 Subject: [PATCH 15/16] add sales callout --- integrations/user-auth/choosing-an-auth-method.mdx | 2 +- integrations/user-auth/overview.mdx | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/integrations/user-auth/choosing-an-auth-method.mdx b/integrations/user-auth/choosing-an-auth-method.mdx index f04c11ffb..e319d4fec 100644 --- a/integrations/user-auth/choosing-an-auth-method.mdx +++ b/integrations/user-auth/choosing-an-auth-method.mdx @@ -3,7 +3,7 @@ title: 'Choosing an Auth Method' description: 'How to decide which auth method is right for your docs' --- -Before your users can access their personalized content, they must be authenticated. Mintlify supports two methods of authenticating users: +Before your users can access personalized content, they must be authenticated. Mintlify supports two methods of authenticating users: 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/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index a43fa92b1..8a10d967b 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -22,6 +22,8 @@ At this time, User Auth cannot provide any of the following: 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 support team](sales@mintlify.com) to explore solutions. + ## How to Use ### Customizing MDX Content From 29fdcf8da804cd8d14a8bc0f685b012c1d1deec4 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Mon, 24 Jun 2024 16:19:55 -0700 Subject: [PATCH 16/16] remove "support" lol --- integrations/user-auth/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/user-auth/overview.mdx b/integrations/user-auth/overview.mdx index 8a10d967b..f9fa229ce 100644 --- a/integrations/user-auth/overview.mdx +++ b/integrations/user-auth/overview.mdx @@ -22,7 +22,7 @@ At this time, User Auth cannot provide any of the following: 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 support team](sales@mintlify.com) to explore solutions. +If you are interested in private docs content, [contact our team](sales@mintlify.com) to explore solutions. ## How to Use