> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GCP

> Federate Google Cloud or GKE identity tokens into short-lived TrueFoundry access tokens.

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](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/overview.md).

## Prerequisites

* A Google Cloud workload that can obtain an identity token (Compute Engine, Cloud Run, GKE with Workload Identity, and similar).
* A [Virtual Account](https://www.truefoundry.com/docs/platform/virtual-account-management.md) 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`):

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/kubernetes.md). Use the **GCP** provider when the JWT is issued by Google (`accounts.google.com`) with `sub` + `email`.

## Configure TrueFoundry

1. **Settings > Security & Access > Identity Providers** → add provider type **GCP**.
2. 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.

3. Map the Virtual Account (or Agent):

**Virtual Account — Claims**

```yaml theme={"dark"}
identity_provider_mapping:
  - identity_provider: gcp-workload
    claims:
      sub: "123456789012345678901"
      email: checkout@your-project.iam.gserviceaccount.com
```

**Agent — Subject** (YAML key is still `claims`)

```yaml theme={"dark"}
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

```bash theme={"dark"}
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](https://www.truefoundry.com/docs/ai-gateway/authentication.md) or APIs. Full exchange details: [Workload Identity Federation](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/overview.md#exchange-the-platform-jwt).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.