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:
- Browser requests
/dashboard. - App renders or redirects to the Auth.js sign-in page.
- The form submits a POST to the GitLab provider endpoint with CSRF protection.
- Auth.js redirects the browser to GitLab.
- GitLab redirects to
/api/auth/callback/gitlab. - 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.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.