Zudoku
Supported Providers

Auth0 Setup

Auth0 is a flexible authentication and authorization platform that integrates seamlessly with Zudoku. This guide walks you through setting up Auth0 authentication for your documentation site.

Prerequisites

If you don't have an Auth0 account, you can sign up for a free Auth0 account that provides 7,000 monthly active users.

Setup Steps

  1. Create Auth0 Application

    Create a new Auth0 application in the Auth0 dashboard:

    • Select type Single Page Web Applications
    • Give your application a descriptive name

  2. Configure Auth0 Application

    In your Auth0 application settings, configure the following:

    Application URLs:

    • Allowed Callback URLs:

      • Production: https://your-site.com/oauth/callback
      • Preview (wildcard): https://*.your-domain.com/oauth/callback
      • Local Development: http://localhost:3000/oauth/callback

    • Allowed Logout URLs:

      • Production: https://your-site.com/oauth/logout-callback
      • Preview (wildcard): https://*.your-domain.com/oauth/logout-callback
      • Local Development: http://localhost:3000/oauth/logout-callback

    • Allowed Web Origins:

      • Production: https://your-site.com
      • Preview (wildcard): https://*.your-domain.com
      • Local development: http://localhost:3000

    Refresh Token Rotation:

    • Allow Refresh Token Rotation: Enabled
    • Rotation Overlap Period: 0 seconds (recommended)

    Keep the default Refresh Token Expiration settings unless you have specific requirements.

  3. Create an Auth0 API:

    • Navigate to the APIs section in the Auth0 dashboard
    • Click Create API
    • Set a name (e.g., "Zudoku API") and an identifier (e.g., https://your-domain.com/api)
    • Choose RS256 as the signing algorithm
    • Save the API

    This step is important. If you skip creating an API, Zudoku will not be able to validate the tokens issued by Auth0, leading to authentication failures.

  4. Configure Zudoku

    Add the Auth0 configuration to your Zudoku configuration file:

    TypeScriptCode
    // zudoku.config.ts
export default {
  // ... other configuration
  authentication: {
    type: "auth0",
    domain: "your-domain.us.auth0.com",
    clientId: "<your-auth0-client-id>",
    audience: "https://your-domain.com/api", // Your Auth0 API identifier
  },
  // ... other configuration
};

    Where:

    • domain: Your Auth0 domain (found in your application's Basic Information)
    • clientId: The Client ID from your Auth0 application settings
    • audience: The identifier of the Auth0 API you created (e.g., https://your-domain.com/api)

Advanced Configuration

Custom Scopes

If you need additional scopes for your API access, you can specify them in the configuration:

TypeScriptCode
authentication: {
  type: "auth0",
  domain: "your-domain.us.auth0.com",
  clientId: "<your-auth0-client-id>",
  scopes: ["openid", "profile", "email", "read:api", "write:api"],
}

Enabling Logout

Zudoku supports logout functionality for Auth0 tenants. For tenants created on or after November 14, 2023, logout is automatically enabled through the OIDC RP-Initiated Logout endpoint.

To enable logout for your Auth0 application:

  1. Ensure your Allowed Logout URLs are configured in Auth0 (see Configure Auth0 Application above)
  2. The logout URL must use the /oauth/logout-callback path (e.g., https://your-site.com/oauth/logout-callback for production)

For older tenants, you may need to enable RP-Initiated Logout in your tenant settings. See the Auth0 logout documentation for details.

Customizing the Prompt Parameter

By default, Zudoku sets prompt="login" in the Auth0 authorization request, which forces users to re-enter their credentials even if they have a valid session. You can customize this behavior using the options.prompt configuration:

TypeScriptCode
authentication: {
  type: "auth0",
  domain: "your-domain.us.auth0.com",
  clientId: "<your-auth0-client-id>",
  audience: "https://your-domain.com/api",
  options: {
    prompt: "", // Omit the prompt parameter to allow silent authentication
  },
}

Valid values for the prompt parameter include:

  • "login" - Force users to re-enter their credentials even if they have a valid session (default)
  • "consent" - Force users to consent to authorization even if they previously consented
  • "select_account" - Force users to select an account (useful for multi-account scenarios)
  • "none" - No prompt is shown; silent authentication only
  • "" (empty string) - Omit the prompt parameter, allowing Auth0 to handle authentication based on session state

When the prompt parameter is omitted (empty string), Auth0 will:

  • Silently authenticate the user if they have a valid session
  • Redirect to the login page if no valid session exists

Customizing Sign-up

By default Auth0 already adds screen_hint=signup when a user clicks Register. To send users to a different page (or hide Register entirely):

TypeScriptCode
authentication: {
  type: "auth0",
  domain: "your-domain.us.auth0.com",
  clientId: "<your-auth0-client-id>",

  // Send Register to a separate URL (absolute → external, relative → in-app)
  signUp: { url: "/register" },

  // Or pass extra params to the Auth0 authorize URL on sign-up
  signUp: { authorizationParams: { connection: "your-signup-connection" } },

  // Hide Register UI entirely. Visual only — configure Auth0 to actually block sign-ups.
  disableSignUp: true,
}

Troubleshooting

Common Issues

  1. Callback URL Mismatch: Ensure your callback URLs in Auth0 exactly match your site's URL, including the /oauth/callback path.

  2. CORS Errors: Add your site's domain to the Allowed Web Origins in Auth0.

  3. Authentication Loop: Check that your Auth0 domain is a plain hostname only (e.g., your-domain.us.auth0.com) without a protocol prefix (https://) or trailing slash.

  4. Token Validation Errors: Ensure the audience in your Zudoku configuration matches the identifier of the Auth0 API you created.

Next Steps

Last modified on
Protected RoutesClerk