# 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](https://auth0.com/signup) that provides 7,000 monthly active users.

## Setup Steps

<Stepper>

1. **Create Auth0 Application**

   [Create a new Auth0 application](https://auth0.com/docs/get-started/auth0-overview/create-applications)
   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](https://manage.auth0.com/#/apis) 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

   :::warning

   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](./overview.md):

   ```typescript
   // 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`)

</Stepper>

## Advanced Configuration

### Custom Scopes

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

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

### Enabling Logout

Dev Portal 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](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
endpoint.

To enable logout for your Auth0 application:

1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
   [Configure Auth0 Application](#setup-steps) above)
2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
   production)

For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
[Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
for details.

### 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:

```typescript
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 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 Dev Portal configuration matches the
   identifier of the Auth0 API you created.

## Next Steps

- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
- Explore other [authentication providers](./authentication.md#authentication-providers) supported
  by Dev Portal - Configure [user permissions](./authentication.md#user-data) based on Auth0 roles