Workload Identity Federation

Workload Identity Federation (WIF) lets Hightouch authenticate as a Google Cloud service account you own, without sharing a service account JSON key. Hightouch's workers run on AWS, so your Google Cloud Workload Identity Pool trusts Hightouch's AWS identity, which then impersonates your service account to access your data.

Prerequisites

• Workload Identity Federation must be enabled for your workspace. Use the Contact Hightouch link above to request access.
• You need administrator access to your Google Cloud project, specifically the roles/iam.workloadIdentityPoolAdmin and roles/iam.serviceAccountAdmin roles.
• The Google Cloud CLI (or Cloud Shell) with your target project active.

Set up Workload Identity Federation

Run each block below in order, in your project's Cloud Shell. The first block sets variables that the rest reuse, so you can paste each one without edits. Make sure the right project is active first with gcloud config set project <id>.

1. Set variables

export HT_PROJECT_ID="$(gcloud config get-value project)"
export HT_PROJECT_NUMBER="$(gcloud projects describe $HT_PROJECT_ID --format='value(projectNumber)')"
export HT_POOL=ht-wif
export HT_PROVIDER=ht-aws
export HT_SA=ht-wif-sa
export HT_SA_EMAIL="$HT_SA@$HT_PROJECT_ID.iam.gserviceaccount.com"
export HT_AWS_ACCOUNT=810028259040
export HT_AWS_PRINCIPAL=arn:aws:iam::810028259040:user/hightouch-worker

2. Create a Workload Identity Pool

gcloud iam workload-identity-pools create "$HT_POOL" \
  --project="$HT_PROJECT_ID" \
  --location=global \
  --display-name="Hightouch WIF"

3. Add an AWS provider that trusts only Hightouch's worker identity

The --attribute-condition is the security boundary: Google issues a token only when the caller is exactly Hightouch's AWS worker identity.

gcloud iam workload-identity-pools providers create-aws "$HT_PROVIDER" \
  --project="$HT_PROJECT_ID" \
  --location=global \
  --workload-identity-pool="$HT_POOL" \
  --account-id="$HT_AWS_ACCOUNT" \
  --attribute-mapping="google.subject=assertion.arn,attribute.aws_identity=assertion.arn" \
  --attribute-condition="assertion.arn == '$HT_AWS_PRINCIPAL'"

4. Create a dedicated service account for Hightouch

gcloud iam service-accounts create "$HT_SA" \
  --project="$HT_PROJECT_ID" \
  --display-name="Hightouch (WIF)"

5. Allow only Hightouch's identity to impersonate the service account

gcloud iam service-accounts add-iam-policy-binding "$HT_SA_EMAIL" \
  --project="$HT_PROJECT_ID" \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/$HT_PROJECT_NUMBER/locations/global/workloadIdentityPools/$HT_POOL/attribute.aws_identity/$HT_AWS_PRINCIPAL"

6. Generate the credential configuration file

gcloud iam workload-identity-pools create-cred-config \
  "projects/$HT_PROJECT_NUMBER/locations/global/workloadIdentityPools/$HT_POOL/providers/$HT_PROVIDER" \
  --service-account="$HT_SA_EMAIL" \
  --aws \
  --output-file=wif-config.json

Grant the service account access to your data

The setup above lets Hightouch sign in as ht-wif-sa, but it doesn't grant access to anything yet. Which roles you need depends on the connector, so check that connector's docs (for example BigQuery) and grant those roles to ht-wif-sa.

Grant them on the resource itself, not just the project. To let Hightouch write to a Cloud Storage bucket, for example, bind roles/storage.objectAdmin (or the narrower roles/storage.objectCreator) on the bucket:

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \
  --member="serviceAccount:$HT_SA_EMAIL" \
  --role=roles/storage.objectAdmin

Upload the configuration to Hightouch

In Hightouch, go to Cloud providers, add a Google Cloud Platform credential, select Workload Identity Federation, and upload the wif-config.json file you generated.

Troubleshooting

storage.objects.create denied (HTTP 403)

You finished the setup, but a sync fails with something like:

{
  "error": {
    "code": 403,
    "message": "ht-wif-sa@YOUR_PROJECT.iam.gserviceaccount.com does not have storage.objects.create access to the Google Cloud Storage object. Permission 'storage.objects.create' denied on resource '...' (or it may not exist)."
  }
}

This means federation is already working: the error names your service account (ht-wif-sa@...), so Google exchanged Hightouch's AWS identity and impersonated the account successfully. What's missing is that account's access to the resource itself. Work through these in order:

1. Use the Policy Troubleshooter. The 403 includes a Policy Troubleshooter link (console.cloud.google.com/iam-admin/troubleshooter/...). It names the exact principal, permission, and resource, and the binding you're missing.
2. Confirm the bucket's project. For a resource it can't see, GCS returns 403 ... (or it may not exist) rather than 404, so a bucket in the wrong project looks just like a permissions problem. Check which project owns it:

   gcloud storage buckets describe gs://YOUR_BUCKET --format="value(name,project_number)"
   

3. Grant the role on the resource, then wait. See Grant the service account access to your data. Bucket and object IAM changes take a minute or two to take effect.
4. Rule out WIF. Impersonate the service account directly, without Hightouch involved, and retry:

   echo test > /tmp/wif-test.txt
   gcloud storage cp /tmp/wif-test.txt gs://YOUR_BUCKET/wif-test.txt \
     --impersonate-service-account=$HT_SA_EMAIL
   

   If that fails too, it's purely a GCP IAM problem on the resource, and fixing the grant fixes the sync. If it works but Hightouch still gets a 403, contact Hightouch.

Learn more

• Workload Identity Federation
• Configuring Workload Identity Federation with AWS
• Google Cloud Platform credentials in Hightouch