From c1e07c0d2c9512d9611679961249526cff82a612 Mon Sep 17 00:00:00 2001 From: mojomast Date: Thu, 22 Jan 2026 02:59:47 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=F0=9F=93=9A=20add=20documentation=20fo?= =?UTF-8?q?r=20remote=20OAuth=20authentication=20with=20SSH=20port=20forwa?= =?UTF-8?q?rding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive documentation explaining OAuth token authentication issue when proxy runs on remote hosts and the SSH port forwarding solution. Updates README.md, DOCUMENTATION.md, and Deployment guide.md with detailed examples and workflows. - Added new section in README.md explaining remote host OAuth problem - Updated DOCUMENTATION.md with section 2.6.4 on SSH port forwarding - Modified Deployment guide.md to standardize SSH tunnel command ordering - Added troubleshooting entry for OAuth callback failures on VPS - Included both SSH tunnel and local authentication export approaches --- DOCUMENTATION.md | 42 ++++++++++++++++++++++++ Deployment guide.md | 8 ++--- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 122 insertions(+), 6 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index f7ebbde5..e78a2005 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -237,6 +237,48 @@ The manager supports loading credentials from two sources, with a clear priority - This is the key to "Stateless Deployment" for platforms like Railway, Render, Heroku - Credentials are referenced internally using `env://` URIs (e.g., `env://gemini_cli/1`) +#### 2.6.4. Remote Host Authentication (SSH Port Forwarding) + +When the proxy is deployed on a remote host (VPS, cloud server, etc.), OAuth authentication requires special handling because OAuth callbacks are sent to `localhost`, which on the remote server refers to the server itself, not your local machine. + +**The Problem:** + +- Proxy runs on remote VPS at `your-vps-ip` +- You attempt to add OAuth credentials using the credential tool on the VPS +- OAuth provider redirects to `http://localhost:PORT/callback` +- On the VPS, `localhost` points to the VPS's localhost, not your local browser +- The callback fails because your browser cannot connect to the VPS's localhost + +**The Solution: SSH Port Forwarding** + +Create an SSH tunnel to forward OAuth callback ports from the VPS to your local machine: + +```bash +# Single provider examples +ssh -L 8085:localhost:8085 user@your-vps-ip # Gemini CLI +ssh -L 51121:localhost:51121 user@your-vps-ip # Antigravity +ssh -L 11451:localhost:11451 user@your-vps-ip # iFlow + +# Multiple providers simultaneously +ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip +``` + +**Workflow:** + +1. **Establish SSH tunnel** (keep this connection open) +2. **Run credential tool on VPS** (in separate SSH session) +3. **Complete browser-based OAuth** - callbacks are forwarded via tunnel +4. **Close SSH tunnel** after authentication completes + +**Alternative Approach: Local Authentication + Export** + +If SSH port forwarding is not feasible: +1. Complete OAuth flows locally on your machine +2. Export credentials to environment variables using credential tool's export feature +3. Deploy `.env` file to remote server + +This approach uses the credential tool's export functionality to generate environment variable representations of OAuth credentials, which can then be deployed to stateless environments without requiring SSH tunnels. + **Gemini CLI Environment Variables:** Single credential (legacy format): diff --git a/Deployment guide.md b/Deployment guide.md index 44c7e033..6a921b9d 100644 --- a/Deployment guide.md +++ b/Deployment guide.md @@ -523,13 +523,13 @@ SSH tunnels forward ports from your local machine to the remote VPS, allowing yo From your **local machine**, open a terminal and run: ```bash -# Forward all OAuth callback ports at once -ssh -L 51121:localhost:51121 -L 8085:localhost:8085 -L 11451:localhost:11451 user@your-vps-ip +# Forward all OAuth callback ports at once (recommended) +ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip # Alternative: Forward ports individually as needed -ssh -L 51121:localhost:51121 user@your-vps-ip # For Antigravity ssh -L 8085:localhost:8085 user@your-vps-ip # For Gemini CLI -ssh -L 11451:localhost:11451 user@your-vps-ip # For iFlow +ssh -L 51121:localhost:51121 user@your-vps-ip # For Antigravity +ssh -L 11451:localhost:11451 user@your-vps-ip # For iFlow ``` **Keep this SSH session open** during the entire authentication process. diff --git a/README.md b/README.md index a7c3c438..9532cfea 100644 --- a/README.md +++ b/README.md @@ -774,6 +774,76 @@ For platforms without file persistence (Railway, Render, Vercel): +
+Remote Host Deployment (SSH Port Forwarding) + +When the proxy is running on a remote host (VPS, cloud server, etc.), OAuth token authentication requires SSH port forwarding. This is because the OAuth callback URL is sent to `localhost`, which on the remote server points to the server itself, not your local machine. + +**The Problem:** + +- You run the proxy on a remote VPS +- You try to add OAuth credentials using the credential tool +- The OAuth provider redirects to `http://localhost:PORT/callback` +- On the VPS, `localhost` refers to the VPS, not your local machine +- The callback fails because your browser can't reach the VPS's localhost + +**The Solution: SSH Port Forwarding** + +Use SSH to tunnel the OAuth callback ports from the VPS back to your local machine. You only need to do this when adding OAuth credentials. + +**Single Provider Examples:** + +```bash +# Gemini CLI (port 8085) +ssh -L 8085:localhost:8085 user@your-vps-ip + +# Antigravity (port 51121) +ssh -L 51121:localhost:51121 user@your-vps-ip + +# iFlow (port 11451) +ssh -L 11451:localhost:11451 user@your-vps-ip +``` + +**Multiple Providers at Once:** + +```bash +# Forward all three OAuth ports simultaneously +ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip +``` + +**Complete Workflow:** + +1. **Establish SSH tunnel** (keep this connection open): + ```bash + ssh -L 8085:localhost:8085 -L 51121:localhost:51121 user@your-vps-ip + ``` + +2. **Run the credential tool on the VPS** (in a separate terminal or SSH session): + ```bash + ssh user@your-vps-ip + cd /path/to/LLM-API-Key-Proxy + python -m rotator_library.credential_tool + ``` + +3. **Complete OAuth authentication**: + - The credential tool will open a browser window + - Because of the SSH tunnel, the callback will be forwarded to your local machine + - Complete the authentication flow as normal + +4. **Close SSH tunnel** after authentication is complete + +**Alternative: Local Authentication + Deploy Credentials** + +If you prefer not to use SSH port forwarding: + +1. Complete OAuth flows locally on your machine +2. Export credentials to environment variables using the credential tool +3. Deploy the `.env` file to your remote server + +See the "Stateless Deployment" section above for details on exporting credentials. + +
+
OAuth Callback Port Configuration @@ -930,11 +1000,13 @@ For OAuth providers (Antigravity, Gemini CLI, etc.), you must authenticate local ```bash # Forward callback ports through SSH -ssh -L 51121:localhost:51121 -L 8085:localhost:8085 user@your-vps +ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip -# Then run credential tool on the VPS +# Then run credential tool on the VPS in a separate terminal ``` +This creates a tunnel that forwards OAuth callback ports from the VPS to your local machine, allowing the browser-based authentication to complete successfully. + **Systemd Service:** ```ini @@ -953,6 +1025,7 @@ WantedBy=multi-user.target ``` See [VPS Deployment](Deployment%20guide.md#appendix-deploying-to-a-custom-vps) for complete guide. +See the [Remote Host Deployment (SSH Port Forwarding)](#remote-host-deployment-ssh-port-forwarding) section above for detailed OAuth setup instructions.
@@ -967,6 +1040,7 @@ See [VPS Deployment](Deployment%20guide.md#appendix-deploying-to-a-custom-vps) f | All keys on cooldown | All keys failed recently; check `logs/detailed_logs/` for upstream errors | | Model not found | Verify format is `provider/model_name` (e.g., `gemini/gemini-2.5-flash`) | | OAuth callback failed | Ensure callback port (8085, 51121, 11451) isn't blocked by firewall | +| OAuth callback failed on remote VPS | Use SSH port forwarding: `ssh -L 8085:localhost:8085 -L 51121:localhost:51121 user@your-vps-ip` | | Streaming hangs | Increase `TIMEOUT_READ_STREAMING`; check provider status | **Detailed Logs:**