Skip to main content

Auth0 Setup

Auth0 is the currently supported production identity provider. The local Docker quick-start uses built-in local-development authentication and does not need an Auth0 tenant.

Create the application​

  1. In Auth0, create an application.
  2. Select Regular Web Application. Do not select Single Page Application.
  3. Create a dedicated Auth0 API for the Multiforum GraphQL backend.
  4. Use the API's identifier as the audience.

For a forum at https://forum.example.com, configure:

Auth0 settingValue
Allowed Callback URLshttps://forum.example.com/auth/callback
Allowed Logout URLshttps://forum.example.com
Allowed Web Originshttps://forum.example.com

The callback path is /auth/callback, not /callback.

Enable Allow Offline Access on the Auth0 API so the Nuxt server session can refresh API access tokens.

Production environment​

Set the shared identity values in .env.production:

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your-regular-web-app-client-id
AUTH0_AUDIENCE=https://api.example.com
NUXT_AUTH0_CLIENT_SECRET=your-regular-web-app-client-secret
NUXT_AUTH0_SESSION_SECRET=your-long-random-session-secret

Generate the session secret independently:

openssl rand -hex 64

The production Compose overlay derives NUXT_AUTH0_APP_BASE_URL from MULTIFORUM_DOMAIN and supplies the same domain, client ID, and audience to the frontend and backend.

Set MULTIFORUM_SUPERADMIN_EMAIL to a tightly controlled, verified Auth0 account. It is the break-glass root identity and bypasses ordinary role checks.

Session storage​

The single-host Compose deployment stores encrypted Auth0 sessions in the persistent frontend-data volume. This supports one frontend replica and survives container recreation. Preserve NUXT_AUTH0_SESSION_SECRET; changing it invalidates or makes existing sessions unreadable.

Horizontally scaled deployments require shared session storage. The hosted serverless deployment can use Upstash Redis, but that is not required for the single-host Compose foundation.

Verify authentication​

After scripts/verify-self-hosting.sh succeeds, complete a real login in the browser. Confirm that:

  1. /auth/login redirects to Auth0.
  2. Auth0 returns to /auth/callback.
  3. The authenticated navigation renders without a client-side flash.
  4. Authenticated GraphQL requests succeed through /api/graphql.
  5. /auth/logout clears the Multiforum session and Auth0 SSO session.

Troubleshooting​

Callback failure​

  • Confirm the application type is Regular Web Application.
  • Match the callback URL exactly, including HTTPS and /auth/callback.
  • Confirm the domain, client ID, client secret, and base URL belong together.

Login succeeds but GraphQL is unauthorized​

  • Confirm AUTH0_AUDIENCE matches the Auth0 API identifier exactly.
  • Confirm the frontend and backend receive the same audience and domain.
  • Confirm offline access is enabled for the API.
  • Inspect frontend and backend logs without exposing tokens.

Users are signed out after recreation​

  • Confirm the frontend-data volume still exists.
  • Confirm NUXT_AUTH0_SESSION_SECRET did not change.

Open-source OIDC providers such as Keycloak and Zitadel remain roadmap work and are not yet supported by the production overlay.