feat(auth): customize the OAuth callback for remote-host logins

[npeshkov]

Description

gws auth login's flow assumes the browser can reach the CLI's callback server on localhost.

When the CLI runs on a remote host (e.g. a cloud development environment), the server is not reachable from the developer's laptop browser, so the OAuth callback has to be redirected to an address other than the laptop's localhost.

This Pull Request adds three optional environment variables that let the caller customize the OAuth flow:

• GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI - sets the redirect URI sent to Google.
• GOOGLE_WORKSPACE_CLI_OAUTH_STATE - a state value passed to the authorization URL (see use cases).
• GOOGLE_WORKSPACE_CLI_OAUTH_PORT - sets the port of the local callback listener.

Implementation notes

• The authorisation code could be percent-encoded on the way between Google's server and the remote host. This will lead to invalid_grant: Malformed auth code, unless the code is decoded by gws.
• When GOOGLE_WORKSPACE_CLI_OAUTH_STATE is set, the state returned on the callback is verified against it. A missing or mismatched value is rejected to guard against forged (CSRF) callbacks.
• The callback server bounds how much it reads from the request line (8 KiB), so a client that never sends a newline cannot exhaust memory (DoS) - relevant now that the port may be reachable from remote networks.
• Moved helper for testing with environment variables from auth.rs to test_support.rs.

Checklist

• My code follows the AGENTS.md guidelines (no generated google-* crates).
• I have run cargo fmt --all to format the code perfectly.
• I have run cargo clippy -- -D warnings and resolved all warnings.
• I have added tests that prove my fix is effective or that my feature works.
• I have provided a Changeset file (e.g. via pnpx changeset) to document my changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: d1cf429

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enables the gws auth login command to work in remote development environments where the local callback server is not directly accessible from the user's browser. By allowing users to override the redirect URI, pin the callback port, and provide a state parameter for CSRF protection, the CLI becomes more flexible for cloud-based workflows. The changes also include necessary security hardening for the callback listener and updated documentation to guide users through this new configuration.

Highlights

• OAuth Callback Customization: Introduced three environment variables (GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT) to allow the OAuth flow to function when the CLI is running on a remote host unreachable via localhost.
• Security Enhancements: Added state verification to the OAuth callback to prevent CSRF attacks and implemented a request size limit on the callback server to mitigate potential DoS risks.
• Test Infrastructure: Refactored the environment variable testing helper into a dedicated test_support.rs module and added comprehensive unit tests for the new OAuth customization logic.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces customization options for the OAuth login callback in the Google Workspace CLI, enabling support for remote-host logins where localhost is unreachable. It adds three new environment variables (GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT) to override the redirect URI, set and verify the OAuth state, and pin the callback port. Additionally, the changes include request-line size limits for security, refactored test helpers, updated documentation, and comprehensive unit tests. There are no review comments, so I have no feedback to provide.

[npeshkov]

Hey @jpoehnelt not sure if you are still active in gws but this tool is great and I'd love to make it even better with this tiny PR. Could you help me find someone with the time to take a look at it? 🙏