Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through connecting BigQuery to Gumloop using Workload Identity Federation (WIF). Instead of per-user OAuth (which forces each teammate to reconnect whenever your GCP session-control window expires) or static service-account key files (which many security policies prohibit), Gumloop acts as an OIDC identity provider that your GCP project federates. Tokens are minted on demand and are short-lived, and no long-lived secrets are ever stored.
Intended Audience: GCP administrators with permission to manage workload identity pools and service accounts (roles/iam.workloadIdentityPoolAdmin and roles/iam.serviceAccountAdmin, or roles/owner). This setup is performed once and 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

1

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.
2

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.
3

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.
4

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
Every claim is derived 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. This is what you will pin your pool to so that only your tenant’s tokens are accepted.
  • 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, any Gumloop tenant’s token could be accepted by your pool. 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'"
  • 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. google.subject is required; the attribute.* mappings let you reference claims in conditions and IAM bindings.
  • attribute-condition — The security gate. Only tokens whose gumloop_org_id equals your organization are allowed. Replace YOUR_GUMLOOP_ORG_ID with the value Gumloop provided.
You do not 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 will impersonate. 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

You will paste these into Gumloop:
  1. GCP Project Number — e.g. 123456789012
  2. Workload Identity Pool Resource Name — the provider resource path: 
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/gumloop-pool/providers/gumloop-oidc
  3. Target Service Account Email — e.g. bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com

​
Step 6: Add the Credential in Gumloop

  1. Go to the Gumloop Credentials page (or your workspace credentials for a shared, team-wide connection).
  2. Click Add Credential and select BigQuery (Workload Identity).
  3. Enter the three values from Step 5 and save.
That’s it. Your BigQuery nodes and agents will now mint short-lived access tokens through Workload Identity Federation, with no OAuth prompts and no daily reconnect.
Add the credential at the workspace level so the whole team shares one keyless connection. Add it at the personal level if you only need it for your own flows.

​
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 must be enabled 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 Gumloop Support.