docs(sheets): describe Connected Sheets BigQuery authorization accurately - #1023
Conversation
…tely The page presented `bigquery.readonly` as a scope Google requires and re-consent as unconditional. Both overstate the constraint. Google requires BigQuery read access; `bigquery.readonly` is the least-privilege scope that grants it, and that is why the Connected Sheets client asks for exactly that one. It is not the only grant that satisfies Google. The client also performs no local scope check: it builds its token source through optionsForAccountScopes, so the stored-grant comparison in tokenSourceForAccountScopesWithStoredScopeCheck is bypassed and the request is authorized by Google against whatever the account already holds. An account whose grant already covers BigQuery read access needs no further consent round, which the previous wording denied. Keep `bigquery.readonly` as the documented default rather than enumerating broader scopes, so least-privilege guidance stays intact while the page stops describing a requirement that is not one. Refs openclaw#938 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
🦞👀 Pull request received. I will update this pull request when review starts. |
clawsweeper
Bot
added
P3
|
Codex review: needs maintainer review before merge. Reviewed August 25, 2026, 11:51 AM ET / 15:51 UTC. ClawSweeper reviewWhat this changesThe PR revises Connected Sheets authorization guidance to cite the required BigQuery scope and require re-authorization only when the stored account lacks the documented grants. Merge readinessThis focused docs PR remains necessary: current main still has the unconditional wording, while the PR accurately states the documented explicit scopes and conditional re-authorization path. Priority: P3 Review scores
Verification
How this fits togetherConnected Sheets commands create a read-only Sheets API client with Sheets and BigQuery scopes. The documentation guides operators in granting access before the client reads data-source metadata and extracts. flowchart LR
A[Stored Google account] --> B[Connected Sheets commands]
B --> C[Connected Sheets client]
C --> D[Sheets and BigQuery scopes]
D --> E[Google Sheets API]
E --> F[Data source metadata and extracts]
Before merge
Agent review detailsSecurityNone. Review metrics
Technical reviewBest possible solution: Merge the narrowly scoped clarification after ordinary maintainer review and completion of the running checks, keeping the upstream guide and explicit two-scope client request as the documented contract. Do we have a high-confidence way to reproduce the issue? Not applicable: this docs-only change is verified against the current client’s explicit scope request and stored-token path. Is this the best way to solve the issue? Yes. The head preserves the supported exact scopes, links the upstream Connected Sheets guide, and removes the unconditional re-authorization instruction without claiming unverified scope supersets. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against 06e86dc46e02. LabelsLabel changes:
Label justifications:
EvidenceWhat I checked:
Likely related people:
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
History |
The note claimed Google authorizes against the existing grant rather than the literal scopes, without qualification. That holds only for stored user OAuth tokens. The service-account path is tried first and asserts the scopes in the signed JWT via google.JWTConfigFromJSON, so domain-wide delegation does require the administrator to have approved exactly those strings — which the preceding paragraph already says. As written the two contradicted each other. Narrow the claim to stored OAuth and name the delegation case as the contrast, so the section reads as one rule with a stated exception. Also attribute the behavior to the Connected Sheets client rather than to gog as a whole: other clients do check the stored grant. Refs openclaw#938 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
clawsweeper
Bot
added
rating: 🦞 diamond lobster
|
Landed in 1251bfc. Thanks @ryo-touch! The final wording keeps Google's explicitly documented Verification:
Issue #938 intentionally remains open for the separately scoped Connected Sheets lifecycle work. |
2 participants
Refs #938.
docs/sheets-connected.mdmakes two claims about BigQuery authorization that are not true, both shipped in 0.37. This corrects them and nothing else.What is wrong today
https://www.googleapis.com/auth/bigquery.readonly". Google requires BigQuery read access.bigquery.readonlyis the least-privilege scope that grants it, and that is why the Connected Sheets client asks for exactly that one — but it is not the only grant Google accepts.The second one matters in practice: a reader with a broadly-scoped token is told to re-authorize, and following that instruction on a token covering many services is a real cost for no gain.
Why (2) is true
The Connected Sheets client performs no local scope check.
NewConnectedSheetsgoes throughoptionsForAccountScopes, which passesrequireStoredGrant=false, so the stored-grant comparison intokenSourceForAccountScopesWithStoredScopeCheck(internal/googleapi/client_auth.go:437) is bypassed. The stored refresh token is used as-is and the request is authorized by Google against whatever the account already holds, not against the literal scope strings gog names.InsufficientScopeErroris only ever constructed inside that skipped branch.On documenting accepted supersets
You asked for a reproducible redacted account-scope listing plus successful Connected Sheets output for the
cloud-platformcase. I could not produce evidence that actually isolates the variable, and I would rather say so than attach a listing that looks like proof and is not.Google accumulates granted scopes. My account's token now holds
bigquery.readonlyalongsidecloud-platform, so any listing from it is consistent with either explanation and proves nothing aboutcloud-platformon its own. Getting a token withcloud-platformbut withoutbigquery.readonlymeans revoking the application's authorization and re-consenting from scratch — on a working token covering 22 services — and I have no separate account I can grant narrowly instead.So this PR deliberately does not enumerate accepted supersets. It states the mechanism (gog does not gate locally; Google decides) and leaves
bigquery.readonlyas the documented least-privilege default. If you want the superset named explicitly, that needs evidence from an account that can be granted narrowly, and I would rather leave it undocumented than assert it from inference.This also walks back part of what I claimed in #938: that my read-path validation ran on a
cloud-platformtoken without re-consent. I cannot now establish whetherbigquery.readonlywas already on that token at the time, so please treat the superset half of that report as unverified. The read-path findings themselves were reproduced and fixed in #1001 and are unaffected.Scope
Docs only, one file, no command or generated-page changes.
make docs-checkpasses (719 command pages, 27 feature pages).The lifecycle PRs are unaffected by the above — a throwaway spreadsheet and scratch dataset do not need a separate account — and I am starting with
refreshas you asked.🤖 Generated with Claude Code