Next.js SSR Authentication#

Overview#

Dify's web frontend (v1.15.0+) uses Next.js App Router with Server-Side Rendering (SSR). During SSR, the Next.js Node process makes direct HTTP calls to the Dify API backend — distinct from browser-side API calls. This means the web container needs its own server-side API URL configuration, and the auth token-refresh flow runs server-side rather than in the browser.

The core SSR auth flow:

1. An RSC (React Server Component) detects a 401 from the API and redirects to GET /auth/refresh 1
2. /auth/refresh posts to the backend /refresh-token endpoint using the request's cookies 2
3. On success, it issues a 303 redirect back to the original page with refreshed Set-Cookie headers; on failure, it redirects to /signin

Key files:

SERVER_CONSOLE_API_URL — SSR-Specific Environment Variable#

Because the Next.js server process needs to reach the Dify API directly (not through the browser-facing public URL), v1.15.0 introduced a dedicated server-side env var: SERVER_CONSOLE_API_URL.

Resolution logic in web/config/server.ts 3:

SERVER_CONSOLE_API_PREFIX = (SERVER_CONSOLE_API_URL || CONSOLE_API_URL) + "/console/api"

SERVER_CONSOLE_API_URL takes precedence; if absent, CONSOLE_API_URL (the browser-facing URL, also a server env var) is used as a fallback. resolveServerConsoleApiUrl() in web/service/console/server uses this prefix to construct absolute URLs for SSR fetches 4. If neither variable resolves, the function returns null and the auth refresh route handler falls back to /signin 5.

Why it matters in Kubernetes/Docker: The web container's Node process must reach the API container over the internal network. External hostnames (used by CONSOLE_API_URL for browser access) are often unresolvable inside the cluster. Set SERVER_CONSOLE_API_URL to the internal DNS name, e.g.:

SERVER_CONSOLE_API_URL=http://dify-api-svc.dify.svc.cluster.local:5001

Leaving this unset while CONSOLE_API_URL points to an external hostname is the most common cause of net::ERR_CONNECTION_CLOSED and silent SSR refresh failures 6.

Not set by entrypoint.sh: web/docker/entrypoint.sh maps CONSOLE_API_URL → NEXT_PUBLIC_API_PREFIX but does not set SERVER_CONSOLE_API_URL — it must be injected separately 7. Both vars are declared as server-only (no NEXT_PUBLIC_ prefix) in web/env.ts 8.

useTimestamp() Hook Regression (v1.15.0)#

The most impactful v1.15.0 regression: anonymous users on public Web App routes (/chat/{token}, /chatbot/{token}, /completion/{token}, /workflow/{token}, /agent/{token}) were being redirected to /signin.

Root cause: useTimestamp() fetches GET /console/api/account/profile to retrieve the user's account timezone. In v1.15.0, this query ran unconditionally (enabled whenever no explicit timezone override was passed). Public Web App routes have no console session, so the request returns 401 → triggers the refresh flow → refresh fails → redirect to /signin. 9 10

Call chain: ChatWithHistoryWrap → useChat() → useTimestamp() → userProfileQueryOptions() → GET /console/api/account/profile → 401 11

Fix (PR #38116): Added web/utils/is-public-webapp-route.ts which checks if the current pathname starts with agent, chat, chatbot, completion, or workflow. The useTimestamp() hook now gates the query so it only runs outside public webapp routes, and falls back to getBrowserTimezone() on public routes 12. The current main branch code already reflects this fix 13.

Related issues: #38043, #38111, #38956, #38457 — all stem from the same root cause. Fix was also confirmed resolved in PR #37915 (a preceding partial fix) and fully closed by PR #38116. 14 15

Workarounds for unpatched v1.15.0 deployments:

• Downgrade only the web container to v1.14.2 while keeping API/worker on v1.15.0
• For reverse-proxy setups: stub GET /console/api/account/profile to return a synthetic 200 for requests with a share-page Referer header

Redirect Loop Debugging#

Redirect loops present as the browser cycling between /signin, /auth/refresh, and the original route. Two distinct causes:

1. useTimestamp() issuing console API calls from public routes (v1.15.0 regression, fixed in PR #38116): The loop is public route → 401 → /auth/refresh → /signin → .... Confirm by checking browser DevTools for GET /console/api/account/profile on share pages. 16

2. SERVER_CONSOLE_API_URL unreachable from the web container: The refresh handler POSTs to the internal API; if it fails (connection error or non-2xx), it redirects to /signin. If /signin also triggers SSR profile checks that fail, a loop follows. Confirm by checking web container logs for fetch errors or ECONNREFUSED at startup. 17

The /auth/refresh route handler has explicit loop prevention — it blocks any redirect_url that points back to /auth/refresh itself 18. But this guard doesn't help when the loop runs through /signin instead.

Checklist:

• Is SERVER_CONSOLE_API_URL set and resolvable from inside the web container? (curl from within the pod)
• Is the web container running v1.15.0 with the unpatched useTimestamp() hook?
• Does the loop affect only public /chat//chatbot routes (hook bug) or also console routes (env var issue)?