Skip to content

feat(auth): Support a fixed OAuth redirect host/port - #106

Open
harrisonhjones wants to merge 1 commit into
xing5:mainfrom
harrisonhjones:feat/fixed-oauth-redirect
Open

harrisonhjones wants to merge 1 commit into
xing5:mainfrom
harrisonhjones:feat/fixed-oauth-redirect

Conversation

@harrisonhjones

Copy link
Copy Markdown

What this changes

Adds three optional environment variables that let you complete the Google login when the server runs on a remote or headless machine and your browser is somewhere else. Nothing changes when they're unset.

Why

The OAuth login calls run_local_server(port=0), which sends Google's redirect to a random localhost port. A browser on another machine can't reach that, so the server can't be authorized there.

How to use it

Variable Meaning
OAUTH_HOST Address the login callback listener binds (default localhost; 0.0.0.0 and other wildcards are refused)
OAUTH_PORT Port the listener binds (default 0, a random port; required with OAUTH_REDIRECT_BASE)
OAUTH_REDIRECT_BASE Public HTTPS URL that forwards to that port, such as a tunnel or reverse proxy
OAUTH_HOST=127.0.0.1
OAUTH_PORT=3500
OAUTH_REDIRECT_BASE=https://my-tunnel.example.com

With a redirect base set, Google is sent <base>/oauth2callback as the redirect URI, and the login URL is logged to stderr instead of opening a browser. This needs a Web application OAuth client with <base>/oauth2callback added as an authorized redirect URI. Both web and installed client JSON files load.

Prior art

The same feature was merged in the Google Calendar MCP as GOOGLE_OAUTH_REDIRECT_BASE: nspady/google-calendar-mcp#198. This change follows its design: a fixed loopback bind and a validated HTTPS base URL.

Testing

  • New tests/test_oauth_flow.py covers the default and fixed binds, input validation, and a full callback over HTTP for both client formats (only the token exchange with Google is faked).
  • The full suite passes: 32 tests, 1 skipped (the existing Google integration test).
  • A manual run with a dummy client showed the listener binds only to loopback, the login URL carries the configured redirect URI, and stdout stays clean.

The OAuth fallback always ran run_local_server(port=0): a random
localhost port that a browser on another machine can't reach, so the
server couldn't be authorized when it runs remotely.

Add three optional env vars. OAUTH_HOST and OAUTH_PORT set where the
callback listener binds (default localhost on a random port, as
before; wildcard addresses are refused). OAUTH_REDIRECT_BASE sets a
public HTTPS URL, such as a tunnel, that forwards to that port: Google
is sent <base>/oauth2callback as the redirect URI, the authorization
URL is logged to stderr instead of opening a browser, and a small
listener on the fixed loopback port completes the token exchange.
With all three unset, behavior is unchanged.
@harrisonhjones
harrisonhjones marked this pull request as ready for review October 21, 2026 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant