BigQuery Workload Identity Federation

This guide walks you through connecting BigQuery to Gumloop using Workload Identity Federation (WIF). Instead of per-user OAuth or static service-account key files, Gumloop acts as an OIDC identity provider that your GCP project federates. Per-user OAuth forces each teammate to reconnect whenever your GCP session-control window expires, and many security policies prohibit static key files. With WIF, Gumloop mints short-lived tokens on demand and never stores a long-lived secret.

Intended Audience: GCP administrators with permission to manage workload identity pools and service accounts (roles/iam.workloadIdentityPoolAdmin and roles/iam.serviceAccountAdmin, or roles/owner). You perform this setup once, and it enables keyless BigQuery access for your whole team.

Why use Workload Identity Federation?

Keyless

No service-account key files to store, rotate, or leak. Gumloop never holds a long-lived secret for your project.

No daily reconnect

Federation is not tied to a human session, so session-control reauth windows never interrupt your agents or flows.

Short-lived tokens

Gumloop mints a fresh, short-lived access token for each request via GCP STS. Nothing durable is persisted.

You stay in control

You decide which service account Gumloop may impersonate and exactly which Gumloop tenant your pool trusts.

How it works

Gumloop mints an OIDC token

At query time, Gumloop signs a short-lived OIDC token identifying your Gumloop organization. Its issuer is https://api.gumloop.com.

GCP STS verifies and exchanges it

Your workload identity pool verifies the token’s signature against Gumloop’s published JWKS and checks your attribute condition, then exchanges it for a federated token.

Gumloop impersonates your service account

The federated token impersonates the target service account you nominate, yielding a short-lived Google access token scoped to BigQuery.

Gumloop queries BigQuery

That access token is used for the BigQuery call, then discarded.

Gumloop’s OIDC issuer publishes its discovery document and public keys, which your pool uses to verify tokens:

Discovery: https://api.gumloop.com/.well-known/openid-configuration
JWKS: https://api.gumloop.com/oauth/jwks

Claims included in the Gumloop OIDC token

Gumloop derives every claim server-side from the authenticated credential owner. None come from user input.

iss: https://api.gumloop.com
sub: gumloop:project:<workspace_id> or gumloop:user:<user_id>
aud: the full resource path of your pool provider
gumloop_org_id: your Gumloop organization ID. Use this to lock down the pool.
gumloop_owner_type: project or user
gumloop_owner_id: the Gumloop workspace or user ID that owns the credential
iat / exp: issued-at and a short (5 minute) expiry

Prerequisites

Before you begin, gather:

Your GCP project ID and project number (gcloud projects describe YOUR_PROJECT_ID --format="value(projectNumber)")
Your Gumloop organization ID, provided by Gumloop. You pin your pool to this value so that your pool accepts only your tenant’s tokens.
Permission to create workload identity pools and service accounts in the project

Then enable the APIs this setup relies on:

gcloud services enable iamcredentials.googleapis.com bigquery.googleapis.com \
  --project="YOUR_PROJECT_ID"

iamcredentials.googleapis.com: required for Gumloop to impersonate your service account (the generateAccessToken call). Without it, token exchange fails with a 403 SERVICE_DISABLED error.
bigquery.googleapis.com: required to run queries.

Pin your pool to your Gumloop organization. Because Gumloop’s issuer can mint tokens for any Gumloop customer, you must set an attribute condition that restricts your pool to your own gumloop_org_id. Without it, your pool could accept any Gumloop tenant’s token. This is the single most important step for tenant isolation.

Step 1: Create a Workload Identity pool

gcloud iam workload-identity-pools create gumloop-pool \
  --project="YOUR_PROJECT_ID" \
  --location="global" \
  --display-name="Gumloop"

Step 2: Add Gumloop as an OIDC provider

Create an OIDC provider in the pool that trusts Gumloop’s issuer, maps the token claims, and restricts access to your Gumloop organization.

gcloud iam workload-identity-pools providers create-oidc gumloop-oidc \
  --project="YOUR_PROJECT_ID" \
  --location="global" \
  --workload-identity-pool="gumloop-pool" \
  --issuer-uri="https://api.gumloop.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.gumloop_org_id=assertion.gumloop_org_id,attribute.gumloop_owner_id=assertion.gumloop_owner_id" \
  --attribute-condition="assertion.gumloop_org_id == 'YOUR_GUMLOOP_ORG_ID'"

Understanding these parameters

issuer-uri: Gumloop’s OIDC issuer. GCP reads https://api.gumloop.com/.well-known/openid-configuration to discover the JWKS used to verify tokens.
attribute-mapping: Maps Gumloop token claims into pool attributes. You must map google.subject. The attribute.* mappings let you reference claims in conditions and IAM bindings.
attribute-condition: The security gate. GCP accepts only tokens whose gumloop_org_id equals your organization. Replace YOUR_GUMLOOP_ORG_ID with the value Gumloop provided.

You don’t need to set --allowed-audiences. Gumloop sets the token audience to the provider’s full resource path, which is the default audience GCP accepts.

Step 3: Create the target service account

This is the identity Gumloop impersonates. Grant it only the BigQuery permissions your team needs.

gcloud iam service-accounts create bigquery-runner \
  --project="YOUR_PROJECT_ID" \
  --display-name="Gumloop BigQuery Runner"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

Follow the principle of least privilege. roles/bigquery.dataViewer + roles/bigquery.jobUser is enough to run read queries. Grant narrower dataset-level roles if you prefer.

Step 4: Allow the pool to impersonate the service account

Grant roles/iam.workloadIdentityUser on the service account to the federated identities from your pool, scoped to your gumloop_org_id attribute.

gcloud iam service-accounts add-iam-policy-binding \
  bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --project="YOUR_PROJECT_ID" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/gumloop-pool/attribute.gumloop_org_id/YOUR_GUMLOOP_ORG_ID"

Use the project number (not the project ID) in the principalSet:// member, and scope it with attribute.gumloop_org_id/... rather than a wildcard so only your organization’s tokens can impersonate the service account.

Step 5: Collect the three values for Gumloop

Paste these three values into Gumloop:

GCP Project Number, for example 123456789012

Workload Identity Pool Resource Name, the provider resource path:

projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/gumloop-pool/providers/gumloop-oidc

Target Service Account Email, for example bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com

Step 6: Add the credential in Gumloop

Go to the Connectors page. For a shared, team-wide connection, use your workspace credentials instead.
Click Add Credential and select BigQuery (Workload Identity).
Enter the three values from Step 5 and save.

Your agents can now use BigQuery through Workload Identity Federation, which mints short-lived access tokens without OAuth prompts.

Use a team connector to share the keyless connection with your team. Use a personal connector for agents you run with your own account.

Troubleshooting

”Permission denied” or no credentials found

Confirm the attribute condition value matches the gumloop_org_id Gumloop provided exactly.
Confirm the principalSet:// binding uses the project number and the same attribute.gumloop_org_id value.
Confirm the service account has roles/bigquery.jobUser (needed to run queries) in addition to a data-read role.

”IAM Service Account Credentials API has not been used… or it is disabled”

The impersonation step calls iamcredentials.googleapis.com, which you must enable in your project. Enable it (and the BigQuery API), then wait a minute or two for the change to propagate:

gcloud services enable iamcredentials.googleapis.com bigquery.googleapis.com \
  --project="YOUR_PROJECT_ID"

“Invalid audience” / token rejected by STS

Make sure the Workload Identity Pool Resource Name you pasted into Gumloop is the full provider path ending in /providers/<provider-id>.

Verifying the issuer is reachable

The discovery and JWKS endpoints are public and should return JSON:

curl https://api.gumloop.com/.well-known/openid-configuration
curl https://api.gumloop.com/oauth/jwks

Additional resources

Need help?

If you run into issues not covered here, reach out to us.

Get started

Core concepts

Enterprise features

Connectors

BigQuery Workload Identity Federation

Why use Workload Identity Federation?

Keyless

No daily reconnect

Short-lived tokens

You stay in control

How it works

Prerequisites

Step 1: Create a Workload Identity pool

Step 2: Add Gumloop as an OIDC provider

Step 3: Create the target service account

Step 4: Allow the pool to impersonate the service account

Step 5: Collect the three values for Gumloop

Step 6: Add the credential in Gumloop

Troubleshooting

”Permission denied” or no credentials found

”IAM Service Account Credentials API has not been used… or it is disabled”

“Invalid audience” / token rejected by STS

Verifying the issuer is reachable

Additional resources

Need help?

​Why use Workload Identity Federation?

Keyless

No daily reconnect

Short-lived tokens

You stay in control

​How it works

​Prerequisites

​Step 1: Create a Workload Identity pool

​Step 2: Add Gumloop as an OIDC provider

​Step 3: Create the target service account

​Step 4: Allow the pool to impersonate the service account

​Step 5: Collect the three values for Gumloop

​Step 6: Add the credential in Gumloop

​Troubleshooting

​”Permission denied” or no credentials found

​”IAM Service Account Credentials API has not been used… or it is disabled”

​“Invalid audience” / token rejected by STS

​Verifying the issuer is reachable

​Additional resources

​Need help?

Why use Workload Identity Federation?

How it works

Prerequisites

Step 1: Create a Workload Identity pool

Step 2: Add Gumloop as an OIDC provider

Step 3: Create the target service account

Step 4: Allow the pool to impersonate the service account

Step 5: Collect the three values for Gumloop

Step 6: Add the credential in Gumloop

Troubleshooting

”Permission denied” or no credentials found

”IAM Service Account Credentials API has not been used… or it is disabled”

“Invalid audience” / token rejected by STS

Verifying the issuer is reachable

Additional resources

Need help?