Authentication

Multiforum uses Auth0 for secure authentication with a hybrid model that provides seamless server-side rendering (SSR) support.

Overview

The authentication system has two layers:

1. Auth hint cookies - Non-sensitive cookies that indicate logged-in state for SSR
2. Secure auth tokens - JWT tokens stored client-side for authenticated API calls

This approach prevents authentication UI flashing during page loads and ensures correct rendering on both server and client.

Authentication Flow

Login

1. User clicks "Log In" and is redirected to Auth0
2. User authenticates with Auth0 (email/password, social login, etc.)
3. Auth0 redirects back with an authorization code
4. Frontend exchanges the code for access and refresh tokens
5. Auth hint cookies are set for SSR detection
6. JWT tokens are stored in localStorage
7. User data is fetched via GraphQL and cached

Session Management

• JWT tokens are automatically checked for expiration every 60 seconds
• Silent token refresh is attempted on 401/UNAUTHENTICATED errors
• Auth hint cookies remain synchronized with token state

Logout

1. Auth hint cookies are cleared
2. localStorage tokens are removed
3. User is redirected to the logout URL

Auth Hint Cookies

The following cookies are used for SSR auth state:

Cookie	Purpose
auth-hint	Indicates whether the user is logged in
username-hint	Current user's username
modProfileName	User's moderation profile display name

These cookies are non-sensitive and only used to render the correct UI state during server-side rendering.

Backend Token Verification

The backend verifies JWT tokens using JWKS (JSON Web Key Set) from Auth0's well-known endpoint:

1. Extract the JWT from the Authorization header
2. Fetch Auth0's public keys via JWKS
3. Verify the token signature and claims
4. Cache user info for 15 minutes to reduce repeated lookups

Testing and Mock Auth

For E2E testing, the backend supports mock authentication:

• Set E2E_MOCK_AUTH=true or PLAYWRIGHT_MOCK_AUTH=true in environment
• Mock tokens are decoded without JWKS verification
• Test users can authenticate programmatically

Required Environment Variables

Frontend

Variable	Description
VITE_AUTH0_DOMAIN	Your Auth0 tenant domain (e.g., your-tenant.auth0.com)
VITE_AUTH0_CLIENT_ID	Auth0 application client ID
VITE_AUTH0_CLIENT_SECRET	Auth0 application client secret
VITE_AUTH0_AUDIENCE	Auth0 API audience identifier
VITE_AUTH0_SCOPE	Permission scopes (e.g., openid profile email)
VITE_AUTH0_URL	Auth0 token endpoint URL
VITE_AUTH0_CALLBACK_URL	URL to redirect after authentication
VITE_LOGOUT_URL	URL to redirect after logout

Backend

Variable	Description
AUTH0_DOMAIN	Your Auth0 tenant domain
AUTH0_CLIENT_ID	Auth0 client ID for server-side operations

Common Issues

UI Flash on Page Load

If you see authentication UI changing after the page loads:

• Check that auth hint cookies are being set correctly
• Verify cookies are accessible during SSR

Hydration Errors

If you see React/Vue hydration mismatches:

• Ensure server and client auth state is synchronized
• Check that useSSRAuth is being used correctly

Token Expiration

If authenticated requests fail unexpectedly:

• Check that token refresh is working
• Verify the Auth0 token expiration settings
• Look for UNAUTHENTICATED errors in the console

Key Components

Component	Location	Purpose
useSSRAuth	composables/auth/useSSRAuth.ts	Auth hint cookies and SSR state
useAuthManager	composables/auth/useAuthManager.ts	Token management and user data
RequireAuth	components/auth/RequireAuth.vue	Auth-aware conditional rendering
Auth0 plugin	plugins/auth0.client.ts	Auth0 Vue SDK configuration