feat: restore domain-wide delegation via GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER

[pureugong]

Summary

Restore service account domain-wide delegation (DWD) support via a single environment variable:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=user@example.com
gws gmail +triage

DWD was removed as collateral damage in PR #253 alongside multi-account cleanup. However, DWD is the standard mechanism for server-to-server Google Workspace integration. Without the sub claim in the JWT assertion, user-scoped APIs (Gmail, Calendar) fail with 400 Precondition check failed, even though the README documents service account usage.

This is a minimal restoration (~15 lines of logic):

• Reads GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER env var
• Calls builder.subject() on ServiceAccountAuthenticator when set
• Shows impersonated_user in gws auth status output
• Documents the env var in help text and README

Does NOT re-add: multi-account support, accounts.json, --account flag, gws auth list, or gws auth default. Those were separate concerns correctly removed in #253.

Context

• Related discussion: Feature Request: Multi-account support #335 (multi-account feature request), Why was Multi-Account Auth introduced in PR:85 and then removed in PR:253 in just over a day #333 (why was it removed?)
• Related issue: Issue Utilizing With a Delegated Gmail Account #528 (delegated Gmail access)
• The yup_oauth2 crate's ServiceAccountAuthenticator::builder().subject() method has always supported this — this PR simply restores the one-line call

Changes

File	Change
src/auth.rs	Read env var, pass to get_token_inner, set builder.subject()
src/auth_commands.rs	Show impersonated_user in auth status JSON
src/main.rs	Add env var to help text
README.md	DWD usage section + env var table row

Test plan

• cargo clippy -- -D warnings passes
• cargo test — 749 tests pass, 0 failures
• Manual verification: gws gmail +triage successfully reads inbox via SA + DWD
• Manual verification: gws auth status shows impersonated_user field
• Without the env var, existing behavior is completely unchanged

[changeset-bot]

🦋 Changeset detected

Latest commit: bb5a4b6

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 restores a critical feature for server-to-server Google Workspace integration: Domain-Wide Delegation (DWD) for service accounts. It re-enables the ability for the CLI to impersonate specific users when making API calls, which is essential for accessing user-scoped services like Gmail and Calendar. The change is carefully scoped to avoid reintroducing complexities of multi-account management that were previously removed.

Highlights

• Domain-Wide Delegation Restoration: Re-enabled support for Google Workspace Domain-Wide Delegation (DWD) for service accounts, allowing impersonation of users via the GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER environment variable.
• Minimal Implementation: Implemented a focused restoration, specifically calling builder.subject() on ServiceAccountAuthenticator when the impersonated user is set, without reintroducing previously removed multi-account features.
• Status Command Enhancement: Updated the gws auth status command to display the currently impersonated user, providing better visibility into DWD configuration.
• Documentation Updates: Added comprehensive documentation in the README.md and command-line help text, detailing how to use the new DWD functionality.

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 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 counter productive. 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 effectively restores domain-wide delegation for service accounts by introducing the GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER environment variable. The changes are well-contained across auth.rs, auth_commands.rs, main.rs, and README.md, and the implementation is minimal as intended. The documentation updates are clear and helpful. I've identified one high-severity issue regarding an inconsistency in how the new environment variable is handled between the authentication logic and the auth status command, which could lead to user confusion. The fix is straightforward.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively restores domain-wide delegation support by introducing the GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER environment variable. The changes are minimal and well-focused, touching authentication logic, command-line output, and documentation as described. My review identifies an opportunity to improve maintainability by refactoring duplicated logic for handling the new environment variable, which aligns with good coding practices and is within the scope of the PR.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request restores domain-wide delegation (DWD) support for service accounts. It introduces the GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER environment variable, which is used to specify an email for impersonation when authenticating with service accounts. The authentication logic in src/auth.rs has been updated to read this variable and apply it as the subject claim in the JWT. Additionally, the README.md has been updated with documentation and examples for DWD, the CLI's usage output now includes the new environment variable, and the auth status command has been enhanced to display the impersonated user if set.

[pureugong]

Hello @jpoehnelt
May I ask if we do have any plan to restore IMPERSONATED_USER back in the roadmap? I wonder if you have any chance to take a look at the PR! Appreciate!

[jpoehnelt]

I am not unable to approve this at this time. Will leave it open for others to see though.

[jpoehnelt]

⚠️ Rebase required — src/ has moved to crates/google-workspace-cli/src/ as part of a workspace refactor (#613). Please rebase on main to resolve path conflicts.

[pureugong]

@jpoehnelt
Thx for the comments! Alright let me first fix the conflict~!