platform/portal
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(dev): pin AUTH_URL to the tenant subdomain #10

Merged
sharang merged 1 commits from fix/auth-url-dev into main 2026-05-19 16:05:45 +00:00
Conversation 0 Commits 1 Files Changed 2
+18 -3
sharang commented 2026-05-19 16:04:42 +00:00
Owner
Copy Link
Copy Source

What

Captures the AUTH_URL gotcha I hit during the live-stack smoke run.

  • .env.example now pins AUTH_URL=http://acme.localhost:3000 and includes a long-form comment explaining why.
  • README's local-dev section adds an 'AUTH_URL gotcha' callout.

Why

Auth.js v5 builds the OAuth redirect_uri from AUTH_URL — not from the request Host header, even with AUTH_TRUST_HOST=true. If you visit http://acme.localhost:3000 while AUTH_URL=http://localhost:3000, Keycloak rejects the token exchange with invalid_grant: Incorrect redirect_uri because the PKCE cookie was set on acme.localhost but the callback URL Auth.js sent points at localhost. Took an hour of poking at Host headers + AUTH_TRUST_HOST + cookie scoping to land on this.

In prod, orca-proxy passes the actual host via X-Forwarded-Host and AUTH_URL is set to the apex (https://breakpilot.com).

Refs: M5.1 follow-up

Risk

Doc + env-template only.

## What Captures the AUTH_URL gotcha I hit during the live-stack smoke run. - `.env.example` now pins `AUTH_URL=http://acme.localhost:3000` and includes a long-form comment explaining why. - README's local-dev section adds an 'AUTH_URL gotcha' callout. ## Why Auth.js v5 builds the OAuth `redirect_uri` from `AUTH_URL` — **not** from the request Host header, even with `AUTH_TRUST_HOST=true`. If you visit `http://acme.localhost:3000` while `AUTH_URL=http://localhost:3000`, Keycloak rejects the token exchange with `invalid_grant: Incorrect redirect_uri` because the PKCE cookie was set on `acme.localhost` but the callback URL Auth.js sent points at `localhost`. Took an hour of poking at Host headers + AUTH_TRUST_HOST + cookie scoping to land on this. In prod, orca-proxy passes the actual host via X-Forwarded-Host and `AUTH_URL` is set to the apex (`https://breakpilot.com`). Refs: M5.1 follow-up ## Risk Doc + env-template only.
sharang added 1 commit 2026-05-19 16:04:43 +00:00
docs(dev): pin AUTH_URL to the tenant subdomain
ci / e2e (pull_request) Has been skipped
Details
ci / image (pull_request) Has been skipped
Details
ci / shared (pull_request) Successful in 6s
Details
ci / test (pull_request) Successful in 28s
Details
f98d20ef0d 
Live-stack debugging caught this: Auth.js v5 builds the OAuth
redirect_uri from AUTH_URL, NOT from the request Host header, even
with AUTH_TRUST_HOST=true. If you visit http://acme.localhost:3000
with AUTH_URL=http://localhost:3000, Keycloak rejects the token
exchange because the PKCE cookie was set on acme.localhost but the
callback URL Auth.js sent was localhost.

Fix in dev: pin AUTH_URL to the subdomain you're testing on. In prod,
orca-proxy passes the right host via X-Forwarded-Host and AUTH_URL
is set to the apex.

Updates .env.example with a long-form note + sets AUTH_URL to the
acme tenant so a copy/paste-and-go workflow Just Works. Adds a
'AUTH_URL gotcha' callout to the local-dev section in README.

Refs: M5.1
CODEOWNERS rules requested review from Benjamin_Boenisch 2026-05-19 16:04:43 +00:00
sharang merged commit 8ab82c8b37 into main 2026-05-19 16:05:45 +00:00
sharang deleted branch fix/auth-url-dev 2026-05-19 16:05:46 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Benjamin_Boenisch
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
Benjamin_Boenisch sharang (Sharang Parnerkar)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: platform/portal#10