docs: rework setup guide with gcloud commands and key permissions

[leet-c1]

What

Reworks docs/connector.mdx to match the reviewed and published Google Workspace setup guide. The published page was updated directly rather than through this file, so this brings the connector's copy back in sync — without it, the next release would sync the older text over the improvements.

No code, capability, or config-schema changes. Documentation only.

Changes

Structure and gcloud

• New Before you begin section listing the required Google Cloud, Workspace, and C1 roles.
• gcloud equivalents alongside every console procedure: project creation, API enablement, service account creation, key creation, key listing, and retrieving the numeric unique ID used for domain-wide delegation.
• New Allow service account key creation section covering both things that block getting a JSON key:
  • iam.serviceAccountKeys.create, granted by the Service Account Key Admin role
  • constraints/iam.disableServiceAccountKeyCreation, enforced by default for organizations created on or after May 3, 2024, with the exact FAILED_PRECONDITION error, the gcloud org-policies describe --effective check, and the project-level exception YAML
  • constraints/iam.serviceAccountKeyExpiryHours, which silently breaks a working connector once a capped key lifetime elapses
• Clarified that the Admin SDK API covers Directory, Reports, and Data Transfer, so there is no separate Data Transfer API to enable despite the admin.datatransfer scope.
• Scope tables replacing the inline purpose lists, split into read-only and read/write tabs.
• Symptom/cause/fix troubleshooting table.

Using the connector as the C1 directory

• New Set Google Workspace as your C1 directory section covering the Directory > Directory sources flow, including that an app is selectable only after its first sync completes.
• Notes that a directory-only deployment needs neither the read/write scopes nor any Google Cloud IAM role.

Consistency pass

• Fixed a contradiction where the project overview called the Cloud Identity API optional while the API table listed it as required.
• Corrected Google Cloud sections that asked for a Google Workspace Super Admin; those steps need Google Cloud permissions, and the Workspace super admin is only required for domain-wide delegation.
• Merged two duplicate callouts about using read-only scopes when not provisioning.
• Fixed What's next? heading level and ordering.

Removal of the Editor role grant

The guide previously told users to grant the service account the Editor role. This drops it in favor of no project role at all.

The connector's access comes entirely from domain-wide delegation configured in the Admin console, so a Cloud IAM project role plays no part in authorizing Workspace API calls. Editor does include iam.serviceAccountKeys.create, so anyone following the old instructions got key creation as a side effect — with Editor removed, the key admin role is now called out explicitly rather than left implied.

This change was reviewed and approved on the published page; it is included here for parity.

One intentional deviation from the published page

The admin.directory.user scope row differs:

• Published: Write. Provision and deprovision accounts
• Here: Write. Provision and deprovision accounts, update user profiles and custom-schema values, and promote and demote super administrators

The published page converted the inline scope list into a table; this file had independently expanded that purpose text to cover update_user_profile, update_user, and make_admin. Those actions are documented here but not yet on the published page. The table structure is taken from the published version and the longer wording preserved, so the row is accurate once the next release syncs.

Verification

• Merged as a three-way merge against the published page's base rather than copied over, so this file's unreleased content is preserved: the capabilities summary line and the update_user_profile / update_user / make_admin rows and their two <Note> blocks.
• Diffed against the published page: the only published line not present here is the scope row above.
• Compiles clean under @mdx-js/mdx (the same compiler the docs verify workflow uses).
• Component tags balanced, code fences even, no duplicate heading anchors, all in-page anchors resolve, and cross-page anchors checked against the target page's actual headings.
• baton_capabilities.json and config_schema.json untouched.

🤖 Generated with Claude Code

[github-actions]

Connector PR Review: docs: rework setup guide with gcloud commands and key permissions

Blocking Issues: 0 | Suggestions: 1 | Threads Resolved: 0
Criteria: Criteria status: loaded .claude/skills/ci-review.md from trusted base dfde8686b3f0.
Review mode: incremental since 9f052e32
View review run: https://github.com/ConductorOne/baton-google-workspace/actions/runs/32276978047

Review Summary

The new commit aa08b6dc addresses the prior finding at docs/connector.mdx:68: Before you begin now separates project creation (roles/resourcemanager.projectCreator, granted at the organization or folder level) from the project-scoped roles, and states explicitly that a project-level role cannot create a project. That matches the gcloud projects create --organization=YOUR_ORG_ID flow the guide teaches, and it closes the gap where "Owner covers all of it" implied a permission that Owner on a single project does not confer. I re-scanned the full PR diff for security and correctness: it is documentation-only, touches no Go source, go.mod, or go.sum, and the action, scope, and enum claims I spot-checked (privacy_levels as a string list, the who_can_post_message and message_moderation_level enum sets, updated_fields returned by update_user only) match pkg/connector/actions.go, pkg/connector/group_actions.go, and pkg/connector/user_actions.go. No new issues found; one prior suggestion remains open below.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• docs/connector.mdx:600 — Still open from an earlier review: the pod label baton: true in the deployment manifest is unquoted, so YAML parses it as a Boolean and kubectl apply rejects it (Kubernetes label values must be strings). Same typing issue already fixed for BATON_PROVISIONING: "true" in the Secret example above. Pre-existing line outside the diff, so it cannot be posted inline.

Prompt for AI agents

Verify each finding against the current code and only fix it if needed.

## Suggestions

In `docs/connector.mdx`:
- Around line 600: In the Kubernetes Deployment manifest, the pod template label `baton: true` is an unquoted YAML Boolean. Kubernetes label values must be strings, so kubectl apply on this manifest fails with a type error. Change the line to `baton: "true"`, matching the already-quoted `BATON_PROVISIONING: "true"` in the Secret example earlier in the same file.

[github-actions]

No blocking issues found.

[github-actions]

Blocking issues found — see review comments.

[github-actions]

No blocking issues found.

Dismissing as stale. This review was submitted against 7f004af; its four comments were addressed in 4221a46 and all six review threads are resolved. The same bot re-ran on 4221a46 and reported "No blocking issues found", but as a COMMENTED review it did not clear this CHANGES_REQUESTED state. All checks now pass, including connector-test, whose earlier failure was a Reports API quotaExceeded against the QA tenant rather than anything in this diff.

[github-actions]

No blocking issues found.

[github-actions]

No blocking issues found.