Skip to main content
This guide walks you through connecting BigQuery to Orchestrivo using Workload Identity Federation (WIF). Instead of per-user OAuth or static service-account key files, Orchestrivo 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, Orchestrivo 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. Orchestrivo 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

Orchestrivo 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 Orchestrivo may impersonate and exactly which Orchestrivo tenant your pool trusts.

​
How it works

1

Orchestrivo mints an OIDC token

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

GCP STS verifies and exchanges it

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

Orchestrivo 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

Orchestrivo queries BigQuery

That access token is used for the BigQuery call, then discarded.
Orchestrivo’s OIDC issuer publishes its discovery document and public keys, which your pool uses to verify tokens:
  • Discovery: https://api.orchestrivo.com/.well-known/openid-configuration
  • JWKS: https://api.orchestrivo.com/oauth/jwks
Orchestrivo derives every claim server-side from the authenticated credential owner. None come from user input.
  • iss: https://api.orchestrivo.com
  • sub: orchestrivo:project:<workspace_id> or orchestrivo:user:<user_id>
  • aud: the full resource path of your pool provider
  • orchestrivo_org_id: your Orchestrivo organization ID. Use this to lock down the pool.
  • orchestrivo_owner_type: project or user
  • orchestrivo_owner_id: the Orchestrivo 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 Orchestrivo organization ID, provided by Orchestrivo. 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:
  • iamcredentials.googleapis.com: required for Orchestrivo 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 Orchestrivo organization. Because Orchestrivo’s issuer can mint tokens for any Orchestrivo customer, you must set an attribute condition that restricts your pool to your own orchestrivo_org_id. Without it, your pool could accept any Orchestrivo tenant’s token. This is the single most important step for tenant isolation.

​
Step 1: Create a Workload Identity pool

​
Step 2: Add Orchestrivo as an OIDC provider

Create an OIDC provider in the pool that trusts Orchestrivo’s issuer, maps the token claims, and restricts access to your Orchestrivo organization.
  • issuer-uri: Orchestrivo’s OIDC issuer. GCP reads https://api.orchestrivo.com/.well-known/openid-configuration to discover the JWKS used to verify tokens.
  • attribute-mapping: Maps Orchestrivo 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 orchestrivo_org_id equals your organization. Replace YOUR_ORCHESTRIVO_ORG_ID with the value Orchestrivo provided.
You don’t need to set --allowed-audiences. Orchestrivo 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 Orchestrivo impersonates. Grant it only the BigQuery permissions your team needs.
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 orchestrivo_org_id attribute.
Use the project number (not the project ID) in the principalSet:// member, and scope it with attribute.orchestrivo_org_id/... rather than a wildcard so only your organization’s tokens can impersonate the service account.

​
Step 5: Collect the three values for Orchestrivo

Paste these three values into Orchestrivo:
  1. GCP Project Number, for example 123456789012
  2. Workload Identity Pool Resource Name, the provider resource path:
  3. Target Service Account Email, for example bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com

​
Step 6: Add the credential in Orchestrivo

  1. Go to the Connectors page. For a shared, team-wide connection, use your workspace credentials instead.
  2. Click Add Credential and select BigQuery (Workload Identity).
  3. 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 orchestrivo_org_id Orchestrivo provided exactly.
  • Confirm the principalSet:// binding uses the project number and the same attribute.orchestrivo_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:

​
“Invalid audience” / token rejected by STS

  • Make sure the Workload Identity Pool Resource Name you pasted into Orchestrivo 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:

​
Additional resources

​
Need help?

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