diff --git a/guides/auth0.mdx b/guides/auth0.mdx new file mode 100644 index 000000000..3ab668527 --- /dev/null +++ b/guides/auth0.mdx @@ -0,0 +1,58 @@ +--- +title: "Using Auth0 with the OAuth Handshake" +description: "If Auth0 is the source of truth for your user data, you can set up Mintlify as an OAuth client app to authenticate your users." +--- + + + **Security Disclaimer**: While we provide this guide to help you integrate Auth0 with Mintlify, please consult with your security team before implementing any authentication solution. Mintlify is not responsible for any security issues that may arise from your specific implementation. + + +## Overview + +This guide walks you through setting up Auth0 as an authentication provider for your Mintlify documentation. By the end, your users will be able to log in to your documentation using their Auth0 credentials. + + + + Log in to your Auth0 dashboard and navigate to **Applications** > **Applications**. Click the **Create Application** button, give your application a name (e.g., "Mintlify"), and select **Regular Web Applications** as the application type. Then click **Create**. + + ![Creating a new application in Auth0](/images/guides/auth0/auth0-create-application.png) + + + After creating your application, you'll be taken to the application settings page. Here, you'll find the essential credentials needed for the OAuth integration: + + ![Auth0 client settings page](/images/guides/auth0/auth0clientsettings.png) + + Make note of the following information: + - **Domain**: This is your Auth0 tenant domain (e.g., `your-tenant.auth0.com`) + - **Client ID**: The public identifier for your application + - **Client Secret**: The secret key for your application (keep this secure) + + You'll need these values for configuring Mintlify in the next step. + + + Navigate to your Mintlify Dashboard and go to the **Settings** > **Authentication** section. Select **OAuth** as your authentication method and you'll see the OAuth configuration form: + + ![Mintlify OAuth client settings](/images/guides/auth0/mintlifyoauthclientsettings.png) + + Fill in the form with the following values: + + - **Authorization URL**: `https://YOUR_AUTH0_DOMAIN/authorize` (replace `YOUR_AUTH0_DOMAIN` with your actual Auth0 domain from step 2) + - **Client ID**: Enter the Client ID from your Auth0 application + - **Client Secret**: Enter the Client Secret from your Auth0 application + - **Scopes**: Leave blank unless you have custom scopes set in Auth0 + - **Token URL**: `https://YOUR_AUTH0_DOMAIN/oauth/token` (replace `YOUR_AUTH0_DOMAIN` with your actual Auth0 domain) + + After filling in these details, click **Save changes** to store your OAuth configuration. + + + Mintlify will generate a unique Redirect URL that Auth0 needs to recognize for the OAuth flow to work properly. + + Copy the Redirect URL from your Mintlify Dashboard's Authentication settings: + ![Mintlify redirect URL](/images/guides/auth0/mintlifyredirecturl.png) + + Return to your Auth0 application settings page, scroll down to the **Application URIs** section, and paste the Redirect URL into the **Allowed Callback URLs** field: + ![Auth0 redirect URL configuration](/images/guides/auth0/auth0redirecturl.png) + + Click **Save Changes** at the bottom of the Auth0 page to apply this configuration. + + \ No newline at end of file diff --git a/images/guides/auth0/auth0-create-application.png b/images/guides/auth0/auth0-create-application.png new file mode 100644 index 000000000..033339486 Binary files /dev/null and b/images/guides/auth0/auth0-create-application.png differ diff --git a/images/guides/auth0/auth0clientsettings.png b/images/guides/auth0/auth0clientsettings.png new file mode 100644 index 000000000..2038abf57 Binary files /dev/null and b/images/guides/auth0/auth0clientsettings.png differ diff --git a/images/guides/auth0/auth0redirecturl.png b/images/guides/auth0/auth0redirecturl.png new file mode 100644 index 000000000..c2a00a5fd Binary files /dev/null and b/images/guides/auth0/auth0redirecturl.png differ diff --git a/images/guides/auth0/mintlifyoauthclientsettings.png b/images/guides/auth0/mintlifyoauthclientsettings.png new file mode 100644 index 000000000..782a7a502 Binary files /dev/null and b/images/guides/auth0/mintlifyoauthclientsettings.png differ diff --git a/images/guides/auth0/mintlifyredirecturl.png b/images/guides/auth0/mintlifyredirecturl.png new file mode 100644 index 000000000..e20f77b14 Binary files /dev/null and b/images/guides/auth0/mintlifyredirecturl.png differ