fix(bigquery): add impersonateServiceAccount to prebuilt config (#2770)

kwkeefer · kkeefer1 · duwenxin99 · web-flow · commit 9c3a748de43e · 2026-03-27T21:05:48.000Z
## Summary Add `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT` env var support to the prebuilt BigQuery configuration, enabling service account impersonation without requiring a custom `--tools-file`. ## Problem The BigQuery source already supports `impersonateServiceAccount` (added in #1641 / #906), but the prebuilt config at `internal/prebuiltconfigs/tools/bigquery.yaml` does not expose it via an environment variable. This forces users who need impersonation to abandon `--prebuilt bigquery` entirely and create a custom `--tools-file` that manually redefines all 9 tools — just to set one field on the source. This is a common need for organizations that use service account impersonation to scope permissions for AI agents, rather than granting broad access to individual user accounts. ## Solution Add a single line to the prebuilt BigQuery YAML: ```yaml impersonateServiceAccount: ${BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT:} ``` The empty default (`:`) means existing users are unaffected — the field is ignored when the env var is not set, preserving full backward compatibility. ## Validation Built the patched binary locally and confirmed: - Without the env var: `SESSION_USER()` returns the personal account (unchanged behavior) - With the env var: `SESSION_USER()` returns the impersonated service account ## PR Checklist - [x] Make sure you reviewed [CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md) - [x] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea - [x] Ensure the tests and linter pass - [x] Code coverage does not decrease (if any source code was changed) - [x] Appropriate docs were updated (if necessary) - [x] Make sure to add `!` if this involve a breaking change 🛠️ Fixes #2769 --------- Co-authored-by: kkeefer1 <kyle_keefer@intuit.com> Co-authored-by: Wenxin Du <117315983+duwenxin99@users.noreply.github.com>
diff --git a/docs/BIGQUERY_README.md b/docs/BIGQUERY_README.md
@@ -76,6 +76,7 @@ export BIGQUERY_PROJECT="<your-gcp-project-id>"
 export BIGQUERY_LOCATION="<your-dataset-location>"  # Optional
 export BIGQUERY_USE_CLIENT_OAUTH="true"  # Optional: true, false, or a custom header name
 export BIGQUERY_SCOPES="<comma-separated-scopes>"  # Optional
+export BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT="<service-account-email>"  # Optional: Service account to impersonate
 ```
 
 Add the following configuration to your MCP client (e.g., `settings.json` for Gemini CLI, `mcp_config.json` for Antigravity):
diff --git a/docs/en/integrations/bigquery/prebuilt-configs/bigquery.md b/docs/en/integrations/bigquery/prebuilt-configs/bigquery.md
@@ -14,6 +14,10 @@ description: "Details of the BigQuery prebuilt configuration."
         OAuth access token for authentication. Defaults to `false`.
     *   `BIGQUERY_SCOPES`: (Optional) A comma-separated list of OAuth scopes to
         use for authentication.
+    *   `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account email
+        to impersonate when making BigQuery and Dataplex API calls. The
+        authenticated principal must have `roles/iam.serviceAccountTokenCreator`
+        on the target service account.
 *   **Permissions:**
     *   **BigQuery User** (`roles/bigquery.user`) to execute queries and view
         metadata.
diff --git a/internal/prebuiltconfigs/tools/bigquery.yaml b/internal/prebuiltconfigs/tools/bigquery.yaml
@@ -20,6 +20,7 @@ sources:
         useClientOAuth: ${BIGQUERY_USE_CLIENT_OAUTH:false}
         scopes: ${BIGQUERY_SCOPES:}
         maxQueryResultRows: ${BIGQUERY_MAX_QUERY_RESULT_ROWS:50}
+        impersonateServiceAccount: ${BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT:}
 tools:
     analyze_contribution:
         kind: bigquery-analyze-contribution
