Blog · Web Blog / Engineering Journal / Authentication
The Localhost OAuth Redirect Bug
The Localhost OAuth Redirect Bug
The 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.
Why the URL was misleading
The 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.
The important distinction was:
Dyno port: internal process detail
Heroku domain: public origin
Custom domain: public canonical origin
The fix
The production deployment was configured with:
AUTH_URL=https://docs.phatysd.me
AUTH_TRUST_HOST=true
The GitLab OAuth application used the exact callback:
https://docs.phatysd.me/api/auth/callback/gitlab
After 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.
A subtle trap: GET versus POST
Opening /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.
The right entry point is /dashboard or the sign-in page, followed by the GitLab button.
Debugging checklist
heroku config:get AUTH_URL -a <APP>
curl -fsS https://docs.phatysd.me/api/auth/signin?callbackUrl=/dashboard \
| rg 'localhost|api/auth/signin/gitlab'
Then 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.
Lesson
OAuth 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.
References
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.