Skip to content

Connect a Google Cloud Project

How-to
On this page
  1. Prerequisites
  2. Step-by-step setup
  3. Step 0 — Enable required GCP APIs
  4. Step 1 — Create a Workload Identity Pool
  5. Step 2 — Create an OIDC provider trusting the orchestrator
  6. Step 3 — Create a service account with deployment permissions
  7. Step 4 — Grant the orchestrator permission to impersonate this SA
  8. Step 5 — Connect via the orchestrator UI
  9. Prepare quotas before your first deployment
  10. Troubleshooting
  11. ”403 — Service account exists but our principal lacks workloadIdentityUser”
  12. ”WIF provider doesn’t trust this orchestrator’s issuer”
  13. ”WIF binding scoped to a different principal”
  14. Probe succeeds but deployments fail with 403 on Compute / Storage / Container
  15. Removing a GCP connection
  16. How this works under the hood
  17. See also

Connects a customer’s Google Cloud project to the AI Orchestrator using Workload Identity Federation (WIF) — the modern, keyless integration pattern used by GitHub Actions, CircleCI, Terraform Cloud, and other SaaS platforms that orchestrate customer infrastructure.

After connecting:

  • The orchestrator can deploy resources to your GCP project
  • No GCP credentials ever leave your project — there’s no service account JSON key file to manage or rotate
  • Trust is scoped to your specific org in the orchestrator via attribute.org_id binding; other customers cannot impersonate your service account even if they use the same orchestrator instance

Prerequisites

  • A GCP project (active) whose billing account is open — check with gcloud billing accounts list: the open column must read True. A linked-but-closed account fails every resource create; see GCP project, billing & IAM issues
  • gcloud CLI installed and authenticated to that project
  • A few minutes — the whole setup is ~5-10 minutes for the first project; subsequent projects are similar

Step-by-step setup

Step 0 — Enable required GCP APIs

The most common cause of “Connect failed with 403” is missing API enablement on the customer project. Run this once per project:

terminal
gcloud services enable \
  sts.googleapis.com \
  iamcredentials.googleapis.com \
  cloudresourcemanager.googleapis.com \
  compute.googleapis.com \
  container.googleapis.com \
  storage.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  secretmanager.googleapis.com \
  logging.googleapis.com \
  monitoring.googleapis.com \
  iam.googleapis.com \
  serviceusage.googleapis.com \
  --project=YOUR_PROJECT_ID
Warning

New projects need one more grant. On freshly created projects, Cloud Build runs as the project’s default compute service account — and Google no longer grants it the storage/build roles legacy projects had. Without them, every image build dies at submit with a storage.objects.get 403. Grant once per project:

terminal
PROJNUM=$(gcloud projects describe YOUR_PROJECT_ID --format='value(projectNumber)')
for R in roles/storage.objectViewer roles/artifactregistry.writer \
         roles/logging.logWriter roles/cloudbuild.builds.builder; do
  gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:$PROJNUM-compute@developer.gserviceaccount.com" \
    --role="$R" --quiet
done

roles/cloudbuild.builds.builder is the one that matters — it carries the source-read, log-write and registry-upload permissions a build needs. The other three are narrower equivalents for projects that prefer to grant them individually. Check which account your builds run as with gcloud builds get-default-service-account --project=YOUR_PROJECT_ID.

Also note new-project quota defaults are low (4 external IPs, 32 vCPUs per region) — request increases before heavy use. Details in GCP project, billing & IAM issues.

The first three (sts, iamcredentials, cloudresourcemanager) are required for WIF authentication itself. The rest are what application deployments actually use: run/cloudbuild/artifactregistry for container builds and Cloud Run services, secretmanager for injected app credentials, logging/monitoring for the live Logs and Metrics panels on every deployment, iam because deployments create their own per-workload service accounts, and serviceusage so the deployer can confirm a service is enabled before it plans against it. Enable these too when your deployments use them: cloudkms.googleapis.com (KMS-protected disks and backups), servicenetworking.googleapis.com and sqladmin.googleapis.com (Cloud SQL on private IP), dns.googleapis.com (managed zones), pubsub.googleapis.com.

Step 1 — Create a Workload Identity Pool

terminal
gcloud iam workload-identity-pools create orch-pool \
  --location=global \
  --display-name="AI Orchestrator Pool"

Pools are containers for federated identities. One pool per project is typical.

Step 2 — Create an OIDC provider trusting the orchestrator

The provider tells GCP which external identity provider (the orchestrator’s OIDC issuer) to trust, and how to map JWT claims to GCP attributes:

terminal
gcloud iam workload-identity-pools providers create-oidc orch-provider \
  --location=global \
  --workload-identity-pool=orch-pool \
  --issuer-uri="https://api.hivedeploy.in" \
  --attribute-mapping="google.subject=assertion.sub,attribute.org_id=assertion.org_id,attribute.cloud_account_id=assertion.cloud_account_id,attribute.environment=assertion.environment"
Warning
the --attribute-mapping value must be one continuous line. Shell soft-wrap or pasting from a document that auto-wraps long lines introduces invisible newlines/spaces that gcloud rejects with a confusing parser error. If you hit that, assign to a variable first and echo "$ATTR_MAPPING" to verify no spaces or newlines before passing it with --attribute-mapping="$ATTR_MAPPING".

After creation, get the provider’s full resource path:

terminal
gcloud iam workload-identity-pools providers describe orch-provider \
  --location=global \
  --workload-identity-pool=orch-pool \
  --format="value(name)"

Output looks like:

projects/123456789012/locations/global/workloadIdentityPools/orch-pool/providers/orch-provider

You’ll paste this into the orchestrator’s connect form.

Step 3 — Create a service account with deployment permissions

terminal
gcloud iam service-accounts create orch-deployer \
  --display-name="AI Orchestrator Deployer"

These are the roles a production-equivalent project runs with — the set was verified against a live project on 2026-11-10, after every GCP deployment campaign to date. Every deployment needs the first group; grant the others for the workloads you deploy:

terminal
PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL="orch-deployer@${PROJECT_ID}.iam.gserviceaccount.com"
 
for role in \
  roles/compute.admin \
  roles/iam.serviceAccountAdmin \
  roles/iam.serviceAccountUser \
  roles/resourcemanager.projectIamAdmin \
  roles/storage.admin \
  roles/serviceusage.serviceUsageConsumer \
  roles/logging.logWriter \
  roles/logging.viewer \
  roles/monitoring.metricWriter \
  roles/monitoring.viewer \
  roles/container.admin \
  roles/run.admin \
  roles/cloudbuild.builds.editor \
  roles/artifactregistry.admin \
  roles/secretmanager.admin \
  roles/cloudkms.admin \
  roles/storage.hmacKeyAdmin; do
  gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="$role" --quiet
done
GroupRolesWhy deployments need them
Every deploymentcompute.admin, iam.serviceAccountAdmin, iam.serviceAccountUser, resourcemanager.projectIamAdmin, storage.admin, serviceusage.serviceUsageConsumerVMs, networks, firewall rules and load balancers; a per-workload service account per deployment, bound to the roles that workload needs; state and artifact buckets; checking that an API is enabled before planning against it
Logs and metrics panelslogging.logWriter, logging.viewer, monitoring.metricWriter, monitoring.viewerthe live Logs and Metrics panels and the health evidence the self-healing loop reads
Containerscontainer.admin, run.admin, cloudbuild.builds.editor, artifactregistry.adminGKE clusters, Cloud Run services, image builds and the registries they push to
Secrets and keyssecretmanager.admin, cloudkms.admininjected application credentials; KMS keys for encrypted disks and backups (KMS key rings cannot be deleted, so expect them to outlive their deployments)
Object-storage credentialsstorage.hmacKeyAdminHMAC keys for workloads that back up to Cloud Storage through the S3-compatible API, such as MongoDB

If you only ever deploy one workload class, drop the groups you do not use — but keep the first two. When a deployment later fails with a 403 naming a permission, the role that carries it belongs in this list; see Troubleshooting GCP deployments.

Step 4 — Grant the orchestrator permission to impersonate this SA

This is the trust grant — it allows JWTs minted by the orchestrator (with org_id matching your orchestrator org) to impersonate this SA.

First find your orchestrator Org ID — visible at the top of the GCP connect form in the orchestrator UI, labeled “Your orchestrator Org ID”. It looks like o-f6bb2d865d8c.

Then:

terminal
PROJECT_NUM=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
YOUR_ORG_ID=o-f6bb2d865d8c   # from the orchestrator UI
 
gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUM/locations/global/workloadIdentityPools/orch-pool/attribute.org_id/$YOUR_ORG_ID"
Note
This binding is scoped to your specific org_id in the orchestrator. Other orgs using the same orchestrator instance cannot impersonate this SA. Their JWTs carry a different org_id claim, which doesn’t match this binding, so GCP STS rejects them.

Step 5 — Connect via the orchestrator UI

Navigate to Cloud Accounts → Connect cloud → GCP and paste:

FieldValue
Account labelFree-text, e.g. prod-gcp
GCP project IDYour project ID (e.g. your-project-abc123)
Workload identity providerThe full path from Step 2 (projects/NNN/locations/.../providers/orch-provider)
Service account emailThe SA email from Step 3 (orch-deployer@your-project-abc123.iam.gserviceaccount.com)
Default regionThe GCP region your deployments target (e.g. us-central1)

Click Connect. The orchestrator runs a smoke test:

  1. Mints a JWT with org_id claim matching your orchestrator org
  2. Exchanges it via sts.googleapis.com for a federated token
  3. Impersonates the SA via iamcredentials.googleapis.com
  4. Reads project metadata as the final check

On success: green “Connected” badge.

Prepare quotas before your first deployment

Connection succeeds against any project — but deployments hit default quotas fast on new projects. The platform checks quota headroom at preflight (you fail in seconds with the exact limit named, not after 20 minutes of churn), but raising limits is a project-owner action only you can take:

QuotaTypical defaultConsumed by
NETWORKS (VPCs)5 / projectone per isolated environment
SSD_TOTAL_GB300–500 / regionGKE node pools (a hardened pool can hold 200GB+)
CPUS8–24 / regionmulti-VM and multi-zone topologies
IN_USE_ADDRESSES8 / regionload balancers, NAT

Raise them in Console → IAM & Admin → Quotas before your first production-shaped deployment.

Warning
If you request bumps through the Cloud Quotas API rather than the console, include a contact email — the API silently accepts requests without one and they never get processed.

More deployment-time patterns (and which ones the platform self-heals): Troubleshooting GCP deployments.

Troubleshooting

”403 — Service account exists but our principal lacks workloadIdentityUser”

Most common: Step 0 API enablement was skipped. Verify with:

terminal
gcloud services list --enabled \
  --filter="name:iamcredentials.googleapis.com" \
  --project=YOUR_PROJECT_ID

If empty → enable per Step 0.

If APIs are enabled, the next most common cause is that the workloadIdentityUser binding (Step 4) doesn’t match your orchestrator’s org_id. Verify the binding contains your actual org_id (no placeholder like <YOUR_ORG_ID>):

terminal
gcloud iam service-accounts get-iam-policy "$SA_EMAIL"

Should show:

yaml
- members:
  - principalSet://iam.googleapis.com/projects/.../attribute.org_id/o-f6bb2d865d8c   # ← real ID
  role: roles/iam.workloadIdentityUser

If the value after attribute.org_id/ is a placeholder or wrong ID, re-run Step 4 with the correct value.

”WIF provider doesn’t trust this orchestrator’s issuer”

The OIDC provider’s --issuer-uri (set in Step 2) doesn’t match the orchestrator’s actual issuer URL. Verify both:

terminal
gcloud iam workload-identity-pools providers describe orch-provider \
  --location=global --workload-identity-pool=orch-pool \
  --format="value(oidc.issuerUri)"

Should print https://api.hivedeploy.in (exactly — no trailing slash, no path differences). If it shows a different URL, the provider was created against the wrong issuer. Delete and recreate the provider with the correct --issuer-uri.

”WIF binding scoped to a different principal”

The federated JWT had a valid signature, but the principal it represents doesn’t match any binding on the SA. Same root cause as the workloadIdentityUser error above — fix per that section.

Probe succeeds but deployments fail with 403 on Compute / Storage / Container

The SA can be impersonated, but it lacks the role to do whatever the deployment is attempting. Either:

  1. Grant the missing role (Step 3 lists starting roles; add more as needed based on the failure)
  2. Enable the missing API (gcloud services enable compute.googleapis.com etc. per Step 0 — extend the list)

The error response body usually names the specific permission missing (e.g. compute.instances.create); search GCP docs for which role includes it.

Removing a GCP connection

terminal
# 1. Delete the binding from the SA (revokes orchestrator's impersonation)
gcloud iam service-accounts remove-iam-policy-binding "$SA_EMAIL" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUM/locations/global/workloadIdentityPools/orch-pool/attribute.org_id/$YOUR_ORG_ID"
 
# 2. Remove the cloud-account row from the orchestrator UI
# (Cloud Accounts → click the account → Remove)

Optional cleanup (if no other orchestrator integration uses these):

terminal
gcloud iam workload-identity-pools providers delete orch-provider \
  --location=global --workload-identity-pool=orch-pool
gcloud iam workload-identity-pools delete orch-pool --location=global
gcloud iam service-accounts delete "$SA_EMAIL"

How this works under the hood

Every time the orchestrator needs to act on your GCP project:

  1. The orchestrator mints a short-lived (5-minute) JWT with claims:

    • iss: https://api.hivedeploy.in (orchestrator’s OIDC issuer)
    • aud: full WIF provider resource URL
    • sub: org:<your-org-id>
    • org_id: <your-org-id> (this is what attribute.org_id maps from)
    • plus context like cloud_account_id, deployment_id, agent_id
  2. The JWT is signed with an RSA key whose public part is published at https://api.hivedeploy.in/.well-known/jwks.json (your GCP WIF provider fetches and caches this).

  3. The orchestrator exchanges the JWT at sts.googleapis.com/v1/token for a federated access token. GCP STS validates the JWT signature, matches the audience to your provider, and projects claims into attribute.* per your mapping.

  4. The orchestrator uses the federated token to call iamcredentials.googleapis.com:generateAccessToken on your SA. GCP IAM checks if the federated principal has workloadIdentityUser — it does (Step 4 binding), scoped to your specific org_id.

  5. The resulting GCP access token is cached in the orchestrator’s Redis for ~55 minutes and used for actual GCP API calls during deployments.

The orchestrator holds no long-lived GCP credentials in this design. Compromise of the orchestrator’s RSA signing key (production: stored in GCP KMS HSM) is the only way to impersonate any customer SA — and even then, only customers who set up the trust binding are at risk.

See also

Was this page helpful?