{"id":27,"type":"docs","title":"Authentication Runbook: GitLab OAuth + Auth.js","slug":"authentication-runbook-gitlab-authjs","canonicalUrl":"https://docs.phatysd.me/content/authentication-runbook-gitlab-authjs","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"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","canonicalUrl":"https://docs.phatysd.me/content/localhost-oauth-redirect-bug"},{"slug":"deployment-runbook-heroku-cloudflare","title":"Deployment Runbook: Heroku + Cloudflare","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"}],"body":"# Authentication Runbook: GitLab OAuth + Auth.js\n\nThis 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.\n\n## Current application model\n\n`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.\n\n```ts\nexport const { handlers, auth } = NextAuth({\n  providers: [GitLab],\n  callbacks: {\n    signIn({ profile }) {\n      return isConfiguredOwner(profile)\n    },\n  },\n})\n```\n\nThe 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.\n\n## Required environment names\n\nUse platform secret storage, not committed files:\n\n```text\nAUTH_SECRET\nAUTH_URL\nAUTH_TRUST_HOST=true\nAUTH_GITLAB_ID\nAUTH_GITLAB_SECRET\nAUTH_GITLAB_OWNER_USERNAME or AUTH_GITLAB_OWNER_ID\n```\n\nAuth.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.\n\nFor this deployment, the public origin is:\n\n```text\nhttps://docs.phatysd.me\n```\n\n## Exact GitLab callback\n\nThe GitLab OAuth application must allow the exact callback URL:\n\n```text\nhttps://docs.phatysd.me/api/auth/callback/gitlab\n```\n\nThe 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.\n\nGitLab 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.\n\n## Correct sign-in flow\n\nThe user-facing entry point is `/dashboard` or the Auth.js sign-in page. A normal flow is:\n\n1. Browser requests `/dashboard`.\n2. App renders or redirects to the Auth.js sign-in page.\n3. The form submits a POST to the GitLab provider endpoint with CSRF protection.\n4. Auth.js redirects the browser to GitLab.\n5. GitLab redirects to `/api/auth/callback/gitlab`.\n6. Auth.js verifies the response, runs the owner gate, and establishes the session.\n\nDo 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.\n\n## Debugging a localhost redirect\n\nIf the sign-in form action contains `https://localhost:<port>`, inspect:\n\n```bash\nheroku config:get AUTH_URL -a <APP>\nheroku config:get AUTH_TRUST_HOST -a <APP>\ncurl -fsS https://docs.phatysd.me/api/auth/signin?callbackUrl=/dashboard | rg 'localhost|api/auth/signin/gitlab'\n```\n\nSet `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.\n\n## Cookie and session checks\n\n- Use HTTPS in production so secure cookies can be set.\n- Ensure the proxy forwards the host and protocol safely.\n- Check that the browser is not retaining a stale callback or failed session cookie.\n- Confirm the owner username/ID matches the GitLab profile actually returned by the provider.\n- Check server logs for the error category, not for secrets or access tokens.\n\n## References\n\n- [Auth.js environment variable inference](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- [Next.js authentication guidance](https://nextjs.org/docs/app/guides/authentication)\n"}