{"id":32,"type":"blog","title":"The Localhost OAuth Redirect Bug","slug":"localhost-oauth-redirect-bug","canonicalUrl":"https://docs.phatysd.me/content/localhost-oauth-redirect-bug","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Engineering Journal > Authentication","topics":["OAuth","Auth.js","GitLab","Production debugging"],"tags":["oauth","authjs","gitlab","localhost","security"],"related":[{"slug":"authentication-runbook-gitlab-authjs","title":"Authentication Runbook: GitLab OAuth + Auth.js","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/authentication-runbook-gitlab-authjs"}],"body":"# The Localhost OAuth Redirect Bug\n\nThe production login page appeared to work until the browser tried to submit the GitLab sign-in form. The form action pointed to `https://localhost:<internal-port>/api/auth/signin/gitlab`. That URL looked like an OAuth problem, but the real bug was origin discovery.\n\n## Why the URL was misleading\n\nThe port came from the Heroku dyno runtime. It was visible in logs, but it was not the public address. Auth.js had generated an absolute action using the wrong host information, so the browser was sent to a machine-local URL instead of the custom domain.\n\nThe important distinction was:\n\n```text\nDyno port:     internal process detail\nHeroku domain: public origin\nCustom domain: public canonical origin\n```\n\n## The fix\n\nThe production deployment was configured with:\n\n```text\nAUTH_URL=https://docs.phatysd.me\nAUTH_TRUST_HOST=true\n```\n\nThe GitLab OAuth application used the exact callback:\n\n```text\nhttps://docs.phatysd.me/api/auth/callback/gitlab\n```\n\nAfter a release restart, the sign-in form action used the custom domain. A simulated CSRF-protected POST redirected to GitLab with the correct callback URI, proving that the application-side flow was fixed before a human login was attempted.\n\n## A subtle trap: GET versus POST\n\nOpening `/api/auth/signin/gitlab` directly in the address bar is not the same as submitting the sign-in form. Auth.js expects the provider action to be invoked through the form flow with CSRF handling. A direct GET can produce a configuration error even when the correct POST flow is healthy.\n\nThe right entry point is `/dashboard` or the sign-in page, followed by the GitLab button.\n\n## Debugging checklist\n\n```bash\nheroku config:get AUTH_URL -a <APP>\ncurl -fsS https://docs.phatysd.me/api/auth/signin?callbackUrl=/dashboard \\\n  | rg 'localhost|api/auth/signin/gitlab'\n```\n\nThen inspect the generated callback URI, GitLab application's Redirect URI, trusted forwarded headers, secure cookies, and owner-gate configuration. Never print OAuth secrets or access tokens while debugging.\n\n## Lesson\n\nOAuth failures often begin as deployment-origin failures. Establish one public origin and use it consistently for canonical URLs, auth configuration, proxy headers, cookies, and provider callbacks.\n\n## References\n\n- [Auth.js environment variables](https://authjs.dev/reference/nextjs)\n- [Auth.js trustHost](https://authjs.dev/reference/core)\n- [Auth.js deployment](https://authjs.dev/getting-started/deployment)\n- [GitLab OAuth applications](https://docs.gitlab.com/integration/oauth_provider/)\n"}