---
id: 32
type: blog
title: "The Localhost OAuth Redirect Bug"
slug: "localhost-oauth-redirect-bug"
canonical_url: "https://docs.phatysd.me/content/localhost-oauth-redirect-bug"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "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
    canonical_url: "https://docs.phatysd.me/content/authentication-runbook-gitlab-authjs"
---

# 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:

```text
Dyno port:     internal process detail
Heroku domain: public origin
Custom domain: public canonical origin
```

## The fix

The production deployment was configured with:

```text
AUTH_URL=https://docs.phatysd.me
AUTH_TRUST_HOST=true
```

The GitLab OAuth application used the exact callback:

```text
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

```bash
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

- [Auth.js environment variables](https://authjs.dev/reference/nextjs)
- [Auth.js trustHost](https://authjs.dev/reference/core)
- [Auth.js deployment](https://authjs.dev/getting-started/deployment)
- [GitLab OAuth applications](https://docs.gitlab.com/integration/oauth_provider/)
