GCP - TrueFoundry Docs

Google Cloud workloads can present a short-lived OIDC JWT from the metadata server (or a GKE projected service-account token) and exchange it for a short-lived TrueFoundry access token — without baking a Virtual Account token into the environment. TrueFoundry requires both sub and email on the Claims / Subject mapping for the gcp provider. For concepts and the shared exchange API, see Workload Identity Federation.

Prerequisites

A Google Cloud workload that can obtain an identity token (Compute Engine, Cloud Run, GKE with Workload Identity, and similar).
A Virtual Account or Agent with the permissions the workload needs.

Get a Google identity token

Metadata server (Compute Engine / Cloud Run / attached SA)

Request an identity token with the audience you will register on TrueFoundry (for example truefoundry):

curl -sS -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=truefoundry&format=full" \
  > /tmp/gcp-jwt

Typical claims when using Google-signed identity tokens:

{
  "iss": "https://accounts.google.com",
  "aud": "truefoundry",
  "sub": "123456789012345678901",
  "email": "checkout@your-project.iam.gserviceaccount.com"
}

GKE projected tokens

If you use GKE projected Kubernetes service-account tokens and the cluster OIDC issuer, you may instead register a Kubernetes Identity Provider and follow Kubernetes. Use the GCP provider when the JWT is issued by Google (accounts.google.com) with sub + email.

Configure TrueFoundry

Settings > Security & Access > Identity Providers → add provider type GCP.
Common values for Google-signed identity tokens:

Field	Value
Issuer URL	`https://accounts.google.com`
Allowed Audiences	Same audience you requested (for example `truefoundry`)
JWKS URI	`https://www.googleapis.com/oauth2/v3/certs`

Confirm iss and jwks_uri against a real token and Google’s discovery document before saving.

Map the Virtual Account (or Agent):

Virtual Account — Claims

identity_provider_mapping:
  - identity_provider: gcp-workload
    claims:
      sub: "123456789012345678901"
      email: checkout@your-project.iam.gserviceaccount.com

Agent — Subject (YAML key is still claims)

identity:
  type: identity-provider-backed
  identity_provider_mapping:
    - identity_provider: gcp-workload
      claims:
        sub: "123456789012345678901"
        email: checkout@your-project.iam.gserviceaccount.com

Required keys for gcp: sub, email. You may add further claim matches when your token includes them and you want to pin them.

Exchange and call TrueFoundry

WORKLOAD_JWT=$(cat /tmp/gcp-jwt)

curl -sS "https://<tenant-host-origin>/<tenant>/oauth2/v1/token" \
  -H 'Content-Type: application/json' \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\",
    \"subject_token\": \"$WORKLOAD_JWT\",
    \"subject_token_type\": \"urn:ietf:params:oauth:token-type:jwt\",
    \"tfy_subject\": \"virtual_account:<virtual-account-name>\"
  }"

<tenant-host-origin> is the issuer origin from OpenID discovery. The exchange path is /{tenant}/oauth2/v1/token (no /api/svc). Prefer token_endpoint from GET https://<tenant-host-origin>/<tenant>/.well-known/openid-configuration. For Agents, set tfy_subject to agent:<agent-name>. Use the returned access_token as Authorization: Bearer on the AI Gateway or APIs. Full exchange details: Workload Identity Federation.

Scope the mapping

Pin both sub and email to one Google service account.
Use a dedicated Google service account per application or environment.
Keep Allowed Audiences aligned with the metadata audience query parameter.

​Prerequisites

​Get a Google identity token

​Metadata server (Compute Engine / Cloud Run / attached SA)

​GKE projected tokens

​Configure TrueFoundry

​Exchange and call TrueFoundry

​Scope the mapping