Vertex AI with Workload Identity

Version requirements

Overview

CrewAI AMP can authenticate to Google Vertex AI using GCP Workload Identity Federation instead of long-lived service account keys. At kickoff, your crew execution fetches a short-lived OIDC token from AMP scoped to your organization and writes a Google Application Default Credentials (ADC) external_account configuration that points at it. The Google Gen AI SDK (invoked via CrewAI's google/ model prefix) then transparently exchanges that OIDC token at GCP STS, optionally impersonates a service account, and calls Vertex AI — all in-process inside the running crew.

The result:

• No Google credentials stored in CrewAI AMP — no service account JSON keys, no API keys. AMP holds only the OIDC signing key it uses to mint tokens.
• Trust is anchored in your GCP project. You decide which CrewAI organization can impersonate which service account.
• The STS exchange happens inside the crew execution, not in AMP's control plane. AMP only mints OIDC tokens; the Google credentials returned by GCP are never seen or persisted by AMP — they live and die inside a single execution.
• Access tokens are refreshed automatically, and the underlying OIDC subject token is rotated before expiry — long-running crews are supported (with one edge case noted below).

How it works

sequenceDiagram
    participant Crew as Crew execution
    participant AMP as CrewAI AMP
    participant STS as GCP STS
    participant IAM as IAM Credentials API
    participant Vertex as Vertex AI

    Crew->>AMP: Request OIDC JWT (aud = WI provider)
    AMP-->>Crew: OIDC JWT
    Note over Crew: Write GOOGLE_APPLICATION_CREDENTIALS
external_account ADC file
    Crew->>STS: Exchange JWT (via google-auth)
    Note right of STS: Validate via JWKS
+ attribute condition
    STS-->>Crew: Federated token
    Crew->>IAM: generateAccessToken (impersonate SA)
    IAM-->>Crew: SA access token
    Crew->>Vertex: generateContent / predict

GCP fetches AMP's public signing keys from a standard OIDC discovery endpoint and validates each token before exchanging it. AMP never sees your GCP service account key, and the federated/SA tokens minted by GCP stay inside the crew execution that requested them — they are not returned to or persisted by AMP's control plane.

Prerequisites

• A GCP project with Vertex AI enabled (aiplatform.googleapis.com).
• The gcloud CLI authenticated as a user with IAM admin on that project. See Appendix: minimum IAM for the specific roles required.
• Your CrewAI organization UUID. Find it in CrewAI AMP at Settings → Organization (use the UUID, not the numeric ID).
• Workload identity for LLM connections enabled on your AMP organization — contact CrewAI support.

The CrewAI AMP OIDC issuer URL is:

https://app.crewai.com

Part 1 — GCP setup

```bash
gcloud iam workload-identity-pools providers create-oidc crewai-amp-oidc \
  --project=PROJECT_ID \
  --location=global \
  --workload-identity-pool=crewai-amp \
  --issuer-uri="https://app.crewai.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
  --attribute-condition="assertion.organization_id == 'YOUR_ORG_UUID'"
```

<Warning>
`YOUR_ORG_UUID` must be your organization **UUID** (the same value used by `attribute.organization` in the principalSet binding below). A wrong value here is the most common cause of `PERMISSION_DENIED` failures during STS exchange.
</Warning>

Record the full provider resource name — you'll need it in Part 2:

```bash
gcloud iam workload-identity-pools providers describe crewai-amp-oidc \
  --project=PROJECT_ID \
  --location=global \
  --workload-identity-pool=crewai-amp \
  --format="value(name)"
# projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/providers/crewai-amp-oidc
```

```bash
gcloud iam service-accounts create crewai-vertex \
  --project=PROJECT_ID \
  --display-name="CrewAI AMP — Vertex AI"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:crewai-vertex@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
```

`roles/aiplatform.user` is the minimum role needed for `generateContent` and `predict`. Tighten further with custom roles if your security policy requires it.

```bash
gcloud iam service-accounts add-iam-policy-binding \
  crewai-vertex@PROJECT_ID.iam.gserviceaccount.com \
  --project=PROJECT_ID \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/attribute.organization/YOUR_ORG_UUID"
```

Part 2 — CrewAI AMP setup

| Field | Value |
|---|---|
| **Name** | A memorable label, e.g. `vertex-ai-prod` |
| **Cloud provider** | `GCP` |
| **GCP Workload Identity Provider** | The full resource name from Part 1, step 3 (`projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/providers/crewai-amp-oidc`) |
| **Default for GCP** | Optional — marks this as the default GCP config for new connections |

Creating workload identity configs requires a role with **manage** access to LLM connections (see [RBAC](/en/enterprise/features/rbac)).

- **Provider:** `Vertex`
- **Workload Identity Config:** the config from the previous step
- **GCP Service Account Email:** the SA you created in Part 1 (e.g., `crewai-vertex@PROJECT_ID.iam.gserviceaccount.com`)

No `GOOGLE_API_KEY` environment variable is required — leave that empty. For region, add a single connection-scoped env var:

- `GOOGLE_CLOUD_LOCATION=global` — recommended default. Vertex's `global` endpoint provides higher availability and is supported by current Gemini 2.x and 3.x models. Set a specific region (e.g. `us-central1`, `europe-west4`) if you need data residency (the global endpoint does **not** guarantee in-region processing) or if you plan to use Vertex features that don't run on `global` (notably **tuning**, **batch prediction** for Anthropic / OpenMaaS models, and **RAG corpus management** — RAG *requests* still work on global). For chat/completion crews, `global` is the right choice.

<Note>
Service account impersonation is configured per-connection (not per-config) so a single workload identity pool can be reused for multiple service accounts with different Vertex permissions.
</Note>

Runtime behavior

For Vertex connections backed by workload identity, the crew does not receive a GOOGLE_API_KEY or service account JSON as a static deploy-time env var. Instead, at kickoff, the running crew:

1. Fetches an OIDC token from AMP, signed with AMP's private key and scoped to your organization (audience = your workload identity provider).

2. Writes the JWT to a temporary file in the execution environment.

3. Writes a Google Application Default Credentials (ADC) config of type external_account that references the JWT file, your STS audience, and (optionally) the service account impersonation URL.

4. Sets the following environment variables for the crew process:

   Env var	Value
   GOOGLE_APPLICATION_CREDENTIALS	Path to the temporary ADC external_account config file
   GOOGLE_CLOUD_PROJECT	Your GCP project number, parsed from the workload identity provider resource name (Google Gen AI SDK accepts either the project ID or the project number)

   No GOOGLE_API_KEY and no GOOGLE_CLOUD_LOCATION are set automatically. Configure GOOGLE_CLOUD_LOCATION on your LLM connection in AMP (recommended default: global).

5. From this point on, google-auth (used by the Google Gen AI SDK) does the STS exchange and SA impersonation transparently on the first Vertex API call, and caches/refreshes the resulting access token automatically.

The crew SDK reads these like any other env var — no code changes required, provided your crew was deployed against crewai>=1.14.3 (see Version requirements).

Long-running crews

Access tokens are automatically refreshed:

• Vertex access tokens (1-hour TTL) are refreshed by google-auth in-process, transparently to your crew code.
• The underlying OIDC subject token (also 1-hour TTL) is rotated before expiry on every kickoff entry point. The crew fetches a fresh OIDC JWT from AMP and rewrites the ADC token file; subsequent STS exchanges pick up the new JWT.

In practice this means:

• Crews that run for less than 1 hour never trigger a refresh — the initial token covers the whole execution.
• Crews that run for multiple hours continue to function as long as kickoff entry points (sync hops, agent steps, etc.) fire during the execution; the refresh buffer ensures the OIDC token is rotated before STS rejects it.
• If a single Vertex API call runs for more than 1 hour (very unusual — typical Gemini responses return in seconds), the OIDC token can expire mid-request and the call will fail. This is the one scenario where token refresh cannot help.

Verification

Run a crew that uses the Vertex connection and tail the execution logs in AMP. A successful generateContent or predict call confirms the full chain — OIDC mint → STS exchange → SA impersonation → Vertex — is wired correctly.

If the crew fails, see Troubleshooting below. Most issues trace back to the GCP-side configuration — the OIDC provider's attribute-condition or the service account's principalSet binding.

Inspecting on the GCP side

You can confirm tokens are being exchanged by looking at Cloud Audit Logs in your GCP project:

• Service: sts.googleapis.com → method google.identity.sts.v1.SecurityTokenService.ExchangeToken
• Service: iamcredentials.googleapis.com → method GenerateAccessToken

A short crew execution produces one ExchangeToken and one GenerateAccessToken entry; longer executions produce additional entries each time the OIDC token is rotated. The protoPayload.authenticationInfo includes the sub and organization_id claims, useful for audit and incident response.

Troubleshooting

Security notes

• The organization_id claim is your security boundary. Your GCP attribute condition must restrict to your organization UUID. Without it, any CrewAI AMP organization could exchange a token through your pool. The sub claim contains the same UUID prefixed with organization: — either could be used, but organization_id matches the bare-UUID form used in the attribute.organization mapping and principalSet binding.
• Service account impersonation is the second boundary. The principalSet binding restricts impersonation to identities whose organization attribute matches your UUID. Use it even when the attribute condition is set — defense in depth.
• Issuer trust is one-way. GCP fetches AMP's public JWKS over HTTPS. AMP never receives any GCP credential.

Appendix: minimum IAM for setup

The user running the gcloud commands above needs, on the target project:

• roles/iam.workloadIdentityPoolAdmin — create pools and providers
• roles/iam.serviceAccountAdmin — create service accounts
• roles/resourcemanager.projectIamAdmin — bind project-level roles
• roles/serviceusage.serviceUsageAdmin — enable required APIs

Or, equivalently, roles/owner on the project.

Related

• Single Sign-On (SSO) — Authentication for the AMP UI and CLI (separate system from LLM workload identity)
• Azure OpenAI Setup — Static-key alternative for Azure OpenAI
• GCP: Workload Identity Federation — Google's reference docs