> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mixlayer.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mixlayer.com/_mcp/server.

# Google Cloud Workload Identity

> Authenticate Google Cloud workloads with metadata-server identity tokens

A Google Cloud workload with an attached service account can request a Google-signed OIDC identity token from the metadata server. Mixlayer verifies that token and exchanges it for a short-lived Mixlayer access token.

This flow uses Google Cloud as the identity provider. You do not need to create a Google workload identity pool or download a service-account key.

## 1. Attach a service account

Run the workload with a dedicated Google service account. Grant the service account only the Google Cloud permissions the workload itself needs.

Get its stable numeric ID:

```bash
export GOOGLE_SERVICE_ACCOUNT_EMAIL="mixlayer-production@example-project.iam.gserviceaccount.com"

export GOOGLE_SERVICE_ACCOUNT_ID=$(
  gcloud iam service-accounts describe "$GOOGLE_SERVICE_ACCOUNT_EMAIL" \
    --format='value(uniqueId)'
)
```

The numeric ID appears in the identity token's `sub` claim and remains stable if the service account's display name changes.

## 2. Configure the Mixlayer provider

Create an OIDC provider in [Workload Identity](https://console.mixlayer.com/app/workload-identity) with:

| Setting          | Value                         |
| ---------------- | ----------------------------- |
| Issuer URI       | `https://accounts.google.com` |
| Allowed audience | `https://api.mixlayer.com`    |
| JWKS source      | OIDC discovery                |

Map the stable service-account identity:

```text
mixlayer.subject = assertion.sub
attribute.email  = assertion.email
```

Admit only the expected numeric service-account ID:

```cel
mixlayer.subject == "123456789012345678901"
```

Use the actual value from `$GOOGLE_SERVICE_ACCOUNT_ID`. Treat the email as a readable attribute, not the primary authorization identifier.

Use `true` as the final authorization rule and grant only the permissions the workload needs.

## 3. Request a Google identity token

From the Google Cloud workload, request an identity token for the same audience configured in Mixlayer:

**`file=`**

```bash file=get-google-identity-token.sh
export MIXLAYER_WIF_AUDIENCE="https://api.mixlayer.com"

export MIXLAYER_SUBJECT_TOKEN=$(
  curl --fail-with-body --silent --show-error --get \
    http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity \
    -H "Metadata-Flavor: Google" \
    --data-urlencode "audience=$MIXLAYER_WIF_AUDIENCE" \
    --data-urlencode "format=full"
)
```

The metadata server is available only from supported Google Cloud environments. Do not proxy or expose it outside the workload.

## 4. Exchange and use the Google token

**`file=`**

```bash file=exchange-google-cloud-workload-identity.sh
MIXLAYER_ACCESS_TOKEN=$(
  jq -n \
    --arg provider "$MIXLAYER_IDENTITY_PROVIDER_ID" \
    --arg token "$MIXLAYER_SUBJECT_TOKEN" \
    '{
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
      subject_token: $token,
      identity_provider_id: $provider
    }' |
  curl --fail-with-body --silent --show-error \
    https://api.mixlayer.com/v1/workload_identity/token \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -er .access_token
)

curl https://mixlayer.ai/v1/models \
  -H "Authorization: Bearer $MIXLAYER_ACCESS_TOKEN"
```

Google identity tokens last one hour. Cache the Mixlayer token in memory until shortly before expiry, then request and exchange a new identity token.

## GKE workloads

GKE workloads can use either a metadata-server identity token from an attached Google service account or a projected Kubernetes ServiceAccount token. For the projected-token approach, follow the [Kubernetes guide](/workload-identity-kubernetes) with the GKE cluster issuer.

## Troubleshooting

* A `404` from the metadata endpoint usually means the service does not expose that endpoint or the workload lacks an attached service account.
* Compare the token's exact `iss`, `aud`, and `sub` with the provider. The requested audience must match one of the provider's allowed audiences.
* If an email transformation fails, request `format=full` or remove that optional mapping and authorize using the numeric `sub`.
* Keep production and non-production service accounts in separate providers or admission policies.