Supported Providers

Auth0 Setup

Copy page

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: Same as callback URLs above

   • 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., "Dev Portal 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, Dev Portal will not be able to validate the tokens issued by Auth0, leading to authentication failures.

4. Configure Zudoku

   Add the Auth0 configuration to your Dev Portal configuration file:

   Code
    
   // 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:

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

Customizing the Prompt Parameter

By default, Dev Portal 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:

Code
 
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

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 includes the protocol (https://) but no trailing slash.

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

Next Steps

• Learn about protecting routes in your documentation
• Explore other authentication providers supported by Dev Portal - Configure user permissions based on Auth0 roles