Skip to main content

GCP Integration

The GCP integration is an authentication provider — it establishes secure, credential-free access to your GCP project using OIDC Workload Identity Federation. It does not give the agent direct access to any data on its own.

Once configured, other integrations (such as BigQuery or PostgreSQL with Cloud SQL) can link to it to obtain GCP credentials at runtime.

How It Works​

  1. You create a Workload Identity Pool with an OIDC Provider that trusts Autoheal
  2. You create a Service Account and bind Autoheal's federated identity to it
  3. At runtime, Autoheal exchanges a short-lived OIDC token for temporary GCP credentials via a two-step token exchange (STS + IAM)
  4. Those credentials are passed to whichever GCP-powered integration needs them — no static keys are stored anywhere

Prerequisites​

  • A GCP project with IAM admin permissions
  • Security Token Service API and IAM Service Account Credentials API enabled
  • Your Autoheal tenant slug (found from your Autoheal URL: https://{tenant-slug}.autoheal.ai)
info

The OIDC audience value used throughout this guide follows the pattern {tenant-slug}-oidc-service — for example, acme-corp-oidc-service.

Setup​

1
Set Your Variables
export GCP_PROJECT_ID="my-gcp-project"
export AUTOHEAL_TENANT_SLUG="your-tenant-slug"
2
Enable Required APIs
gcloud services enable \
  sts.googleapis.com \
  iamcredentials.googleapis.com \
  --project=${GCP_PROJECT_ID}
3
Create Workload Identity Pool
gcloud iam workload-identity-pools create autoheal-pool \
  --project=${GCP_PROJECT_ID} \
  --location=global \
  --display-name="Autoheal OIDC Federation"
4
Create OIDC Provider
gcloud iam workload-identity-pools providers create-oidc autoheal-provider \
  --project=${GCP_PROJECT_ID} \
  --location=global \
  --workload-identity-pool=autoheal-pool \
  --issuer-uri="https://app.autoheal.ai" \
  --attribute-mapping="google.subject=assertion.aud[0]" \
  --allowed-audiences="${AUTOHEAL_TENANT_SLUG}-oidc-service"
info

The attribute mapping must use assertion.aud[0] (not assertion.aud). The OIDC token's aud claim is a JSON array, and GCP requires google.subject to be a string. Using aud[0] extracts the first element.

5
Create Service Account
gcloud iam service-accounts create autoheal-sa \
  --project=${GCP_PROJECT_ID} \
  --display-name="Autoheal Service Account"
6
Bind Autoheal's Federated Identity
PROJECT_NUMBER=$(gcloud projects describe ${GCP_PROJECT_ID} --format="value(projectNumber)")
SA_EMAIL="autoheal-sa@${GCP_PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts add-iam-policy-binding ${SA_EMAIL} \
  --project=${GCP_PROJECT_ID} \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/autoheal-pool/subject/${AUTOHEAL_TENANT_SLUG}-oidc-service"
7
Get the Provider Resource Name

Copy this — you'll paste it into Autoheal:

echo "projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/autoheal-pool/providers/autoheal-provider"
8
Add Integration in Autoheal
  1. Go to Integrations → Google Cloud Platform
  2. Enter a name (e.g., "Production GCP")
  3. Fill in:
    • GCP Project ID: Your project ID
    • Workload Identity Pool Provider: The resource name from the previous step
    • Service Account Email: autoheal-sa@{your-project-id}.iam.gserviceaccount.com
  4. Click Test Connection, then Save

Network Requirements​

DirectionFromToPurpose
GCP → AutohealGCP Workload Identity Federationhttps://app.autoheal.ai/.well-known/openid-configuration and JWKS endpointGCP fetches Autoheal's signing keys to validate the OIDC token
Autoheal → GCPAutoheal platformsts.googleapis.comExchanges OIDC token for a federated access token
Autoheal → GCPAutoheal platformiamcredentials.googleapis.comExchanges federated token for a service account access token

Security​

  • No stored credentials: Autoheal never stores GCP service account keys. Tokens are short-lived and expire automatically.
  • Tenant isolation: Each Autoheal tenant has a unique OIDC identity — one tenant cannot access another tenant's GCP resources.
  • Revocable: Remove the Workload Identity User binding at any time to immediately revoke Autoheal access.

Troubleshooting​

Test Connection fails with 'permission denied'
  • Verify the Service Account has the roles/iam.workloadIdentityUser binding for Autoheal's federated identity
  • Check that the subject in the binding matches your tenant's audience value ({your-tenant-slug}-oidc-service)
  • Ensure the Workload Identity Pool Provider resource name uses the project number (not project ID)
'google.subject must be of type STRING' error

The OIDC provider's attribute mapping is using assertion.aud instead of assertion.aud[0]. Fix it:

gcloud iam workload-identity-pools providers update-oidc autoheal-provider \
  --project=YOUR_PROJECT_ID \
  --location=global \
  --workload-identity-pool=autoheal-pool \
  --attribute-mapping="google.subject=assertion.aud[0]"
How to revoke Autoheal access
export GCP_PROJECT_ID="your-project-id"
export AUTOHEAL_TENANT_SLUG="your-tenant-slug"
SA_EMAIL="autoheal-sa@${GCP_PROJECT_ID}.iam.gserviceaccount.com"
PROJECT_NUMBER=$(gcloud projects describe ${GCP_PROJECT_ID} --format="value(projectNumber)")

gcloud iam service-accounts remove-iam-policy-binding ${SA_EMAIL} \
  --project=${GCP_PROJECT_ID} \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/autoheal-pool/subject/${AUTOHEAL_TENANT_SLUG}-oidc-service"

Next Steps​

Once your GCP integration is configured, connect the GCP-powered integrations you need. Each one links to this GCP integration for authentication and has its own setup guide covering the additional permissions required: