Improvements to documentation with regards to remote OAuth issue #97
Conversation
…rt forwarding 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
|
I'm beginning my review of the documentation improvements for remote OAuth authentication. I'll examine the new SSH port forwarding instructions and the troubleshooting guide to ensure everything is clear and accurate. |
![mirrobot-agent[bot]](https://avatars.githubusercontent.com/in/2140342?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overall Assessment
This PR provides excellent and much-needed documentation for handling OAuth authentication on remote hosts. The explanation of why localhost callbacks fail on a VPS and how to use SSH port forwarding as a solution is clear and will save users a lot of troubleshooting time.
Architectural Feedback
The approach of documenting both the SSH tunnel method and the "local auth + export" alternative is great, as it covers different deployment styles (persistent VPS vs. stateless cloud).
Key Suggestions
- Consistency: I noticed the iFlow port (
11451) was missing from a few of the aggregate examples inREADME.md. Keeping all three ports (8085, 51121, 11451) in the "all-at-once" examples ensures all providers are covered. - Headless VPS Context: I suggested a small clarification regarding the "opening browser" behavior, as users on headless servers will typically need to copy-paste a URL manually.
- Actionability: Added a suggestion to include the specific
--exportflag in the alternative workflow section to make it easier for users to follow.
Questions for the Author
None. The documentation is very straightforward and helpful.
This review was generated by an AI assistant.
|
|
||
| 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 |
There was a problem hiding this comment.
It might be helpful to include the actual command for exporting credentials here, e.g., python -m rotator_library.credential_tool --export, so users don’t have to hunt for it.
| 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 |
There was a problem hiding this comment.
There is a slight formatting inconsistency with the indentation of the comment here (triple space vs single space on other lines).
| ssh -L 51121:localhost:51121 user@your-vps-ip # For Antigravity | |
| ssh -L 51121:localhost:51121 user@your-vps-ip # For Antigravity |
|
|
||
| **Complete Workflow:** | ||
|
|
||
| 1. **Establish SSH tunnel** (keep this connection open): |
There was a problem hiding this comment.
The iFlow port (11451) is missing from this example, while it is included in the examples just above (line 809). Adding it here would ensure consistency.
| 1. **Establish SSH tunnel** (keep this connection open): | |
| ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip |
| python -m rotator_library.credential_tool | ||
| ``` | ||
|
|
||
| 3. **Complete OAuth authentication**: |
There was a problem hiding this comment.
On many remote servers (especially headless VPS instances), the credential tool cannot automatically open a browser window. It usually prints a URL for the user to copy. Clarifying this (e.g., "The tool will provide a URL to open in your local browser") would be more accurate for VPS users.
| | 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` | |
There was a problem hiding this comment.
The iFlow port (11451) is also missing from this troubleshooting entry. Including it would ensure all OAuth providers are covered.
| | OAuth callback failed on remote VPS | Use SSH port forwarding: `ssh -L 8085:localhost:8085 -L 51121:localhost:51121 user@your-vps-ip` | | |
| | OAuth callback failed on remote VPS | Use SSH port forwarding: `ssh -L 8085:localhost:8085 -L 51121:localhost:51121 -L 11451:localhost:11451 user@your-vps-ip` | |
1 participant
Summary
Added comprehensive documentation explaining the OAuth token authentication issue when the proxy runs on remote hosts and the SSH port forwarding solution.
Changes
Details
This documentation addresses the issue where OAuth callbacks to
localhostfail on remote VPS deployments becauselocalhoston the VPS refers to the VPS itself, not the user's local machine. The solution uses SSH port forwarding to tunnel OAuth callback ports back to the local machine during credential setup.Two approaches are documented:
Example Usage
SSH Port Forwarding (for adding credentials directly on VPS)
Alternative: Local Authentication + Export
.envfile to remote serverImportant
Improves documentation for handling OAuth callback issues on remote hosts using SSH port forwarding, with updates in
README.md,DOCUMENTATION.md, andDeployment guide.md.README.md: Adds "Remote Host Deployment (SSH Port Forwarding)" section explaining OAuth callback issues and SSH port forwarding solution.DOCUMENTATION.md: Introduces section 2.6.4 on remote host authentication using SSH port forwarding.Deployment guide.md: Updates SSH tunnel commands to standardized examples.README.md.This description was created by
for c1e07c0. You can customize this summary. It will automatically update as commits are pushed.