Docs · Web Blog / Operations / Authentication

Authentication Runbook: GitLab OAuth + Auth.js

Authentication Runbook: GitLab OAuth + Auth.js

This runbook covers the single-owner GitLab login used by this Next.js application. It focuses on configuration boundaries, exact callback URLs, and the failure mode where production generates a localhost sign-in action.

Current application model

auth.ts configures Auth.js with the GitLab provider and an owner gate. The provider authenticates the GitLab user; the signIn callback then checks the configured owner username or ID. Authentication and authorization are separate decisions.

export const { handlers, auth } = NextAuth({
  providers: [GitLab],
  callbacks: {
    signIn({ profile }) {
      return isConfiguredOwner(profile)
    },
  },
})

The dashboard and every Server Action that changes content must still verify the session. Hiding a button or redirecting in proxy.ts is not the authorization boundary.

Required environment names

Use platform secret storage, not committed files:

AUTH_SECRET
AUTH_URL
AUTH_TRUST_HOST=true
AUTH_GITLAB_ID
AUTH_GITLAB_SECRET
AUTH_GITLAB_OWNER_USERNAME or AUTH_GITLAB_OWNER_ID

Auth.js v5 infers provider credentials from AUTH_{PROVIDER}_ID and AUTH_{PROVIDER}_SECRET. AUTH_SECRET is required in production. When the app is behind a proxy, AUTH_TRUST_HOST allows Auth.js to use trusted forwarded host/protocol information; only enable it when the proxy and deployment path are controlled.

For this deployment, the public origin is:

https://docs.phatysd.me

Exact GitLab callback

The GitLab OAuth application must allow the exact callback URL:

https://docs.phatysd.me/api/auth/callback/gitlab

The protocol, hostname, path, and any port must match. Do not use the internal Heroku dyno port, localhost, or the .herokuapp.com origin unless that is intentionally registered as a separate development callback.

GitLab application setup is under the user profile's Access → Applications area. Store the generated client secret immediately and rotate it if it has been exposed. GitLab's documentation recommends an SSL redirect URI.

Correct sign-in flow

The user-facing entry point is /dashboard or the Auth.js sign-in page. A normal flow is:

  1. Browser requests /dashboard.
  2. App renders or redirects to the Auth.js sign-in page.
  3. The form submits a POST to the GitLab provider endpoint with CSRF protection.
  4. Auth.js redirects the browser to GitLab.
  5. GitLab redirects to /api/auth/callback/gitlab.
  6. Auth.js verifies the response, runs the owner gate, and establishes the session.

Do not paste /api/auth/signin/gitlab into the address bar as a normal GET. The provider action is designed to be submitted from the sign-in form. A GET may produce a configuration error even when the POST flow is correctly configured.

Debugging a localhost redirect

If the sign-in form action contains https://localhost:<port>, inspect:

heroku config:get AUTH_URL -a <APP>
heroku config:get AUTH_TRUST_HOST -a <APP>
curl -fsS https://docs.phatysd.me/api/auth/signin?callbackUrl=/dashboard | rg 'localhost|api/auth/signin/gitlab'

Set AUTH_URL to the public HTTPS origin, restart/release the app, and test the generated form again. Do not fix this by registering an internal port with GitLab; the port belongs to the dyno runtime.

Cookie and session checks

  • Use HTTPS in production so secure cookies can be set.
  • Ensure the proxy forwards the host and protocol safely.
  • Check that the browser is not retaining a stale callback or failed session cookie.
  • Confirm the owner username/ID matches the GitLab profile actually returned by the provider.
  • Check server logs for the error category, not for secrets or access tokens.

References

Agent access

Choose a representation.

Published content only
Human pageYou are reading the human-facing canonical page.
Current page

Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.