---
id: 27
type: docs
title: "Authentication Runbook: GitLab OAuth + Auth.js"
slug: "authentication-runbook-gitlab-authjs"
canonical_url: "https://docs.phatysd.me/content/authentication-runbook-gitlab-authjs"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "Web Blog > Operations > Authentication"
topics:
  - "Authentication"
  - "GitLab OAuth"
  - "Auth.js"
  - "Security"
tags:
  - "authjs"
  - "gitlab"
  - "oauth"
  - "security"
  - "nextauth"
related:
  - slug: "localhost-oauth-redirect-bug"
    title: "The Localhost OAuth Redirect Bug"
    type: blog
    canonical_url: "https://docs.phatysd.me/content/localhost-oauth-redirect-bug"
  - slug: "deployment-runbook-heroku-cloudflare"
    title: "Deployment Runbook: Heroku + Cloudflare"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"
---

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

```ts
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:

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

```text
https://docs.phatysd.me
```

## Exact GitLab callback

The GitLab OAuth application must allow the exact callback URL:

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

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

- [Auth.js environment variable inference](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/)
- [Next.js authentication guidance](https://nextjs.org/docs/app/guides/authentication)
