Feature request: --subject flag (or env var) for service-account impersonation on user-context APIs (Keep, Admin Directory, etc.)

Open
#776 0 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
rust

Research direction

No source file or test is named. Start by locating the Rust service-account credential construction and CLI global-argument or environment-variable parsing, then reproduce the Keep notes request with domain-wide delegation. Done means a supported subject setting reaches the credentials and enables the documented user-context API flow without breaking existing service-account authentication.

Written by the indexing model from the issue text.

Description

Problem

Some Google Workspace APIs only work with a service account that impersonates a user via domain-wide delegation. Notable examples:

  • Keep API (keep.googleapis.com) — explicitly states user OAuth is unsupported; only service accounts work, and they need to act on behalf of a real user (since notes belong to users).
  • Admin Directory write operations on certain entities.
  • Cloud Identity device APIs.

gws today supports two auth modes:

  • User OAuth via gws auth login
  • Service account via GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json

In the SA path, there's no way to set the JWT subject (the user to impersonate). Without it, gws keep notes list returns:

{
  "error": {
    "code": 403,
    "message": "Request had insufficient authentication scopes.",
    "reason": "unknown"
  }
}

even when the SA has DWD authorized for https://www.googleapis.com/auth/keep on the target domain.

Reproduction

  1. Create an SA in GCP, enable DWD via Workspace Admin (admin.google.com → Security → API controls → Domain-wide Delegation) with scope https://www.googleapis.com/auth/keep.
  2. Export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json.
  3. Run gws keep notes list.
  4. 403 — there is no user context attached to the request.

Proposed solution

Add one of:

  • CLI flag --subject <[email protected]> on commands (or globally on gws auth login).
  • Env var GOOGLE_WORKSPACE_CLI_SUBJECT or GOOGLE_WORKSPACE_CLI_IMPERSONATE.

Internally this maps to subject=... when constructing google.oauth2.service_account.Credentials (or the equivalent Go/Rust binding depending on the implementation language).

Workaround used today

Standalone Python script using google-auth directly:

creds = service_account.Credentials.from_service_account_file(
    "sa.json",
    scopes=["https://www.googleapis.com/auth/keep"],
    subject="[email protected]",
)

Works, but means losing all the schema-discovery / formatting / pagination ergonomics that gws ships with.

Why it matters

Without subject impersonation, gws-keep, parts of gws-admin-directory, and other DWD-only flows are effectively dead code in the skill set — the auth path can't be completed.

Happy to PR this if there's interest in the direction.

Dominant language
Rust
Stars
32.3k
Forks
2k
Avg merge
16h 3m
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from googleworkspace/cli

All issues in googleworkspace/cli

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.