Set up GCP BigQuery service credential

A GCP BigQuery service credential lets a Glean agent query BigQuery datasets as a service account rather than on behalf of an individual user. Glean uses service account impersonation to mint short-lived access tokens, so you never upload or manage long-lived service account keys.

Glean handles authentication automatically. Tokens are minted server-side, and the agent never sees a static key.

• Authentication: Service account impersonation which are short-lived tokens and no key upload is required
• Scope: The BigQuery projects, datasets, and tables the target service account can access
• Access: Read-only

Prerequisites

Before configuring your agent, ensure you have the following:

• An active GCP project with the BigQuery datasets the agent will query.
• A dedicated service account created specifically for the agent, for example: bq-reader@<your-gcp-project>.iam.gserviceaccount.com.
• The following IAM roles granted to that service account:
  • BigQuery Data Viewer (roles/bigquery.dataViewer) on the projects or datasets the agent will query.
  • BigQuery Job User (roles/bigquery.jobUser) on the project, so the agent can run queries.
• The Glean query endpoint service account identity associated with your deployment, required to configure the impersonation relationship.
• A Glean administrator who can create service credentials.
• The GCP BigQuery template enabled for your deployment. If you don't see it in the list of templates, contact your Glean representative to turn it on.

Step 1: Identify the Glean query endpoint service account

The Glean query endpoint runs as a specific GCP service account using the following format:

query-endpoint@<your-glean-gcp-project>.iam.gserviceaccount.com

Select your preferred method below to locate this service account:

Using the CLI

Choose the command that matches your access level.

Via gcloud (requires IAM permissions on the Glean project):

gcloud iam service-accounts list \
  --project="<YOUR_GLEAN_GCP_PROJECT>" \
  --filter="email:query-endpoint@"

Via kubectl (requires cluster access to the GKE deployment):

kubectl get serviceaccount gke-qe \
  --namespace=default \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'

Using the GCP Console

1. Open the Google Cloud Console and navigate to IAM & Admin > Service Accounts within your Glean GCP project.
2. Search for the service account prefix: query-endpoint@.

Step 2: Grant impersonation access on the target service account

To mint short-lived tokens, the Glean query endpoint service account must be granted the Service Account Token Creator (roles/iam.serviceAccountTokenCreator) role on the target service account.

Select your preferred configuration method:

Using the CLI

Execute the following gcloud command to add the required IAM policy binding. Replace the placeholder variables with your specific service account identifiers.

# Set your service account variables
TARGET_SA="bq-reader@<your-gcp-project>.iam.gserviceaccount.com"
QE_SA="query-endpoint@<YOUR_GLEAN_GCP_PROJECT>.iam.gserviceaccount.com"

# Grant the Service Account Token Creator role
gcloud iam service-accounts add-iam-policy-binding "$TARGET_SA" \
  --member="serviceAccount:$QE_SA" \
  --role="roles/iam.serviceAccountTokenCreator"

Using the GCP Console

1. Open the Google Cloud Console and navigate to IAM & Admin > Service Accounts in the GCP project that owns the target service account.
2. Select the checkbox next to your target service account (for example, bq-reader@...).
3. If the info panel on the right is not visible, click Show Info Panel in the top-right corner.
4. In the permissions panel, click Grant Access.
5. In the New principals field, enter the full email address of your Glean query endpoint service account.
6. In the Select a role dropdown, select Service Account Token Creator.
7. Click Save.

Step 3: Confirm the target service account permissions

Make sure the target service account has the BigQuery roles it needs:

• BigQuery Data Viewer (roles/bigquery.dataViewer) on the projects or datasets the agent will query.
• BigQuery Job User (roles/bigquery.jobUser) on the project, so the agent can run queries.

Step 4: Create the service credential in Glean

1. In Glean, go to Admin console → Platform → Tools → Service credentials.
   
2. Click Add.
3. Select GCP BigQuery under Service credentials.
4. Fill in these fields:
   • Credential name: A human-readable name for the credential, for example, "BigQuery Reader — my-project".
   • Description: A brief description of what this credential is used for.
   • Service account email: The full email address of the target service account, for example, bq-reader@<your-gcp-project>.iam.gserviceaccount.com.
   • Audience: Which users or groups can attach this credential to agents.
5. Select Save.

Step 5: Attach the credential to an agent

Agent builders can attach the credential from the Service credentials tab in the agent builder. After you attach it, the agent can query BigQuery datasets using short-lived tokens minted through service account impersonation.

1. Go to Agents in Glean.

2. Select the agent to which you want to add the service credentials.

3. In the Tools tab, select Service credentials and select the GCP BigQuery service credential you created.

   

Step 6 (optional): Set a BigQuery quota for the service account

To protect against runaway costs from agent queries, it is recommended to set a custom quota on the BigQuery usage of the service account:

1. In the Google Cloud Console, go to IAM & Admin > Quotas in the project.
2. Filter for BigQuery API > Query usage per day per user.
3. Create a quota override scoped to the target service account, for example, 1 TB/day.

A project-level quota gives you a deterministic safety net that is independent of agent behavior.

Verify it works

Success

Ask the agent to run a simple query, for example, "list the tables in <your-dataset>." If it returns results, the credential is working.

What the agent can do

With a GCP BigQuery credential attached, the agent can query BigQuery data the target service account can access:

• Run read-only SQL queries
• Inspect schemas for accessible datasets and tables
• Summarize query results

Glean mints a short-lived token for each request, and the agent can't exceed the IAM permissions granted to the target service account.

Security and operational notes

• Impersonation, not keys: Glean mints short-lived tokens through impersonation, so there is no long-lived key to store, upload, or leak.
• Injected server-side: the agent runtime never receives a static credential. Glean adds the token only to requests bound for Google APIs.
• Least privilege: grant the target service account only the BigQuery roles the agent needs, on only the datasets it must reach.
• Cost control: set a BigQuery quota on the service account to cap daily query spend.
• Revocation: to cut off access, remove the Service Account Token Creator binding for the Glean query endpoint service account on the target service account.

Troubleshooting

The Glean query endpoint service account is missing the Service Account Token Creator role on the target service account. Re-grant it, following Step 2.

The target service account is missing a BigQuery role. Confirm it has BigQuery Data Viewer on the target datasets and BigQuery Job User on the project, following Step 3.

The service account can authenticate and run jobs but can't read the target dataset or tables. Check dataset- and table-level permissions.

You may be looking in the wrong project or lack access. Use the CLI or GCP Console methods in Step 1, or contact your Glean representative for the exact identity.

The template isn't enabled for your deployment. Contact your Glean representative to turn it on.

See also

• Service credentials overview
• Service account impersonation