Repository navigation
fix(oauth): keep the loopback callback port stable for static clients - #1069
Merged
Merged
Conversation
A statically configured `oauth.client_id` got a fresh loopback callback port on every login, so the redirect_uri changed each time. Providers that require an exact callback URL and reject wildcards — GitHub OAuth Apps among them — could never be made to work. Three causes, three fixes: - `persistDCRCredentials()` only *preserved* an already-stored callback port, and only DCR-succeeded flows ever stored one. A static-client login therefore persisted port 0. It now persists the port of the live callback server for that upstream, falling back to the stored value when no callback server is running. - With client_id set and port 0, the next login took the "legacy DCR credentials without stored port" branch and wiped the record. A static client is never re-registered, so clearing it is always wrong; both clearing branches (legacy and port-changed) now skip static clients. - `oauth.redirect_uri` was a dead config field: documented, diffed in DetectConfigChanges, never read. It is now honored as an explicit operator pin — the port is used as the preferred callback port and the configured URI is sent to the provider verbatim. It is validated (http, loopback host, explicit port, /oauth/callback path); a malformed value or an unavailable pinned port fails the login with an actionable error instead of silently falling back to a random port. Related #975
Deploying mcpproxy-docs with
|
| Latest commit: |
8e0e2e3
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://bf255194.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://fix-oauth-static-client-call.mcpproxy-docs.pages.dev |
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Dumbris
enabled auto-merge (squash)
August 27, 2026 05:44
This was referenced Aug 27, 2026
github-actions Bot
pushed a commit
that referenced
this pull request
Aug 27, 2026
… and validated (#1070) * fix(oauth): make the redirect_uri pin actually reachable, diagnosable and validated PR #1069 made the per-server `oauth.redirect_uri` field load-bearing for the first time. QA of the merged change found five defects on that newly-live path. - An `::1` pin was accepted, blessed by a test and advertised in the docs, but the callback listener was hard-coded to `net.Listen("tcp", "127.0.0.1:PORT")`. The provider was handed a `[::1]` URL nothing listened on, so the browser redirect was refused and the login hung to the callback timeout. The pin now carries its host: `localhost` and `127.0.0.1` bind IPv4, `::1` binds IPv6. - Every log line in `createOAuthConfigInternal` and in the callback-server manager went to `zap.L()`, which this repo never replaces, so all of it was discarded — including #1069's new "fail loudly" errors, and the docs claim that they appear in the logs. The connection's own logger is threaded in. - A malformed pin was a permanent connect failure reported as "failed to create OAuth config - server may not support OAuth", which never names the culprit. The parse error and the "pinned port unavailable" reason now reach the user-visible error, and the write surfaces (REST config API, MCP `upstream_servers`) reject a bad value up front. The boot path deliberately does not: a value already on disk must not stop the daemon from starting. The Gemini importer no longer copies a callback URL mcpproxy cannot honor. - `StartCallbackServer` returned a cached server without honoring the requested port, so a pinned reconnect after a timed-out flow failed against a free port. It now re-binds — but only when the cached server has no waiter parked on it, preserving the invariant #1068 established. - The pinned path skipped the stored-credential read, so Spec-022 legacy cleanup never ran and a DCR registration issued against a different port was reused forever. The read always runs now; only the port choice short-circuits. Docs: correct the wildcard-callback advice in mcp-go-oauth.md (GitHub OAuth Apps reject `http://127.0.0.1:*`), drop the non-existent `redirect_port` field from the callback-mismatch error page, fix the `:8080` example that collided with mcpproxy's own listener, and resolve the port-allocation contradiction. Follow-up to #1069. Refs #975, #1066. * docs(oauth): correct the GitHub wildcard-matching claim GitHub added per-callback-URL wildcard matching in August 2026, so "rejects wildcards" is no longer accurate. The argument for pinning the port is unchanged and is what GitHub actually documents: wildcard matching covers subdomains and subdirectory paths, while the host and port must still match the registered callback exactly. --------- Co-authored-by: Algis Dumbris <gordon.greatests@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related #975
The bug
With a static
oauth.client_idconfigured, mcpproxy allocated a fresh loopback callback port on every login, so theredirect_urisent to the provider changed each time. GitHub OAuth Apps (and other providers) require the callback URL to match the registered one exactly and reject wildcards, so such an integration could never be made to work — there is no single URL you can register.Before / after, same isolated instance, same script, two consecutive login cycles with
oauth.client_id: test-client:The three parts of the fix
(a)
persistDCRCredentials()persists the live callback port.It previously only preserved an already-stored port (
callbackPort := 0then read the record), and only the DCR-succeeded branches ever wrote one. A static-credential login therefore persistedclient_idwith port0. It now resolves the port from the callback server that is actually running for that upstream (resolveCallbackPortForPersistence), falling back to the stored value when no callback server is up, so a refresh-only path never downgrades a known port to 0.(b) The clearing branches skip static clients.
With a non-empty
client_idand port0, the next login hit the "Legacy DCR credentials found without stored port, clearing for re-registration" branch and wiped the record — after whichpreferredPortstayed0andnet.Listen("tcp", "127.0.0.1:0")handed out a new port. A statically configured client is never re-registered, so clearing it is always wrong. Both clearing branches (legacy-no-port and port-changed) now skip whenserverConfig.OAuth.ClientID != "". Genuine DCR clients keep the original Spec 022 behavior, guarded by its own test.(c)
oauth.redirect_uriis honored as an explicit operator pin.The field existed at
internal/config/config.go:707, was diffed inDetectConfigChanges, was documented inspecs/006-oauth-extra-params/quickstart.md— and was never read:internal/oauth/config.gounconditionally usedcallbackServer.RedirectURI. Operators believed they had pinned a port and had not. It now pins the preferred callback port, and the configured URI is sent to the provider verbatim (solocalhostvs127.0.0.1spelling is preserved). NewParsePinnedRedirectURIvalidates it —httpscheme, loopback host, explicit port,/oauth/callbackpath, no query/fragment — and a malformed value aborts the flow with an actionable error rather than silently falling back to a random port. An unavailable pinned port fails the same way, since any other port produces a redirect the provider will reject.Pinning verified end to end as well (
"redirect_uri": "http://127.0.0.1:18987/oauth/callback"):Tests
Written first, watched fail against unmodified production code, then implemented. The regression test drives real production code (
oauth.CreateOAuthConfig→markOAuthComplete) against the existingtests/oauthserverprovider — no new fake provider.Red before the fix:
Green after:
New coverage:
internal/upstream/core/oauth_callback_port_test.go,internal/oauth/redirect_uri_pin_test.go(including aParsePinnedRedirectURIvalidation table and a guard that legacy DCR credentials are still cleared).How the local verification was run
Isolated instance only — high port, scratch
--data-dirand--config,HEADLESS=1;~/.mcpproxy/untouched andscripts/test-api-e2e.shnever invoked. The upstream wastests/oauthserver(go run ./tests/oauthserver/cmd/server -port 18951), configured with a staticclient_id. Each login cycle:POST /api/v1/servers/oauthtest/login→ complete the provider's login form → deliver the callback to the loopback URI. The second login was forced the way a real provider rotation does — restart the provider (new signing keys), then restart the upstream, which lands inAuthentication required. Nologoutbetween cycles, since a full logout deletes the whole token record (including the port) by design.The standalone test-provider
main.gogained mcpproxy's own/oauth/callbackpath in the pre-registered client's redirect URIs; without it the provider rejects a real mcpproxy login withinvalid_request.Gates
go test -race ./internal/oauth/... ./internal/upstream/...— okgo test ./internal/config/... ./internal/storage/... ./tests/...— okgo build ./...andgo build -tags server -o /dev/null ./cmd/mcpproxy— okgolangci-lint run --config .github/.golangci.yml ./internal/oauth/... ./internal/upstream/... ./tests/...— 0 issuesNot touched
The callback-channel / state-dispatch region (
handleCallback, the sharedCallbackChan,StartCallbackServer's reuse path,waitForOAuthCallbackAsync) is untouched — a separate bug lives there.