Authenticate to Google Cloud using an agent's own identity

Agents can access Google Cloud APIs and other resources using their own identity. Google recommends this method for agents hosted on Google Cloud to interact with other Google Cloud services.

When an agent acts on its own authority, it uses its primary SPIFFE identity to request Google Cloud access tokens.

Before you begin

1. Verify that you have chosen the correct authentication method.
2. Create and deploy an agent with Agent Identity enabled.
3. Verify that you have the roles required to complete this task.

Required roles

To get the permissions that you need to grant an agent access to Google Cloud services, ask your administrator to grant you the following IAM roles on the target resource:

• To grant access to an agent:
  • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
  • Security Admin (roles/iam.securityAdmin)
• Recommended roles for the agent identity:
  • Agent Context Editor (roles/aiplatform.agentContextEditor)
  • Agent Default Access (roles/aiplatform.agentDefaultAccess)
  • Vertex AI User (roles/aiplatform.user)
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
  • Browser (roles/browser)
  • Storage Object Viewer (roles/storage.objectViewer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Grant access to agents

To let your agent access a Google Cloud service, you must grant the agent's identity the required roles on the target resource.

In IAM allow policies, agent identities use principal identifiers.

To grant an agent access to a resource, use the Google Cloud console or the gcloud CLI.

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Reference the agent identity in your code

The Google Cloud client libraries automatically use Agent Identity when your agent is deployed to a supported Google Cloud environment.

The following Python snippet shows how to manually use Agent Identity credentials to call the Cloud Vision API using the Agent Development Kit (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Optional: Opt out of certificate-bound tokens

A default Google-managed Context-Aware Access policy helps secure Agent Identity credentials. Beyond the Agent Gateway, the policy enforces Demonstrating Proof of Possession (DPoP) by authenticating the agent's access token. The policy also requires mutual TLS (mTLS) to access the Agent Gateway. This requirement helps ensure that only the intended, trusted runtime environment, such as a Cloud Run container or a Google Kubernetes Engine (GKE) Pod, can use the certificate-bound tokens. This security baseline makes stolen credentials unreplayable, helping protect against credential theft and account takeover (ATO).

Certificate binding helps protect two types of agent credentials:

• Google Cloud access tokens: Short-lived OAuth 2.0 access tokens that authenticate requests to Google Cloud APIs and other resources (*.googleapis.com).
• OpenID Connect (OIDC) ID tokens: JSON Web Tokens (JWTs) that authenticate requests to external services and to tools and services hosted on Google Cloud runtimes, such as Cloud Run (*.mtls.run.app) or GKE.

Opt out of binding for all access and ID tokens

Opting out of the default Context-Aware Access policy and certificate-bound tokens across the runtime environment isn't recommended. Setting GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false removes token-binding protection for both Google Cloud access tokens and OIDC ID tokens, making these short-lived tokens vulnerable to theft or replay attacks.

However, you can opt out across the runtime environment in the following rare cases:

• You have specific token-sharing requirements among agents.
• You must inject the token directly into the request header.
• Your agent can't authenticate and returns a 401 UNAUTHENTICATED error.

To opt out across the runtime environment, set the following environment variable when you deploy your agent:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Opt out for individual ID token requests

By default, supported Google Auth client libraries cryptographically bind OIDC ID tokens to the agent's unique X.509 certificate by including the certificate fingerprint in the token's cnf (x5t#S256) claim.

Some services, such as Cloud Run, enforce certificate binding when the cnf claim is present. If your agent calls these services over a non-mTLS endpoint, such as a standard *.run.app URL, or if a target endpoint doesn't require certificate binding, you can opt out for individual ID token requests. This setting affects only that request and doesn't disable certificate binding for Google Cloud access tokens.

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

Deploy the agent

When you deploy your agent to Google Cloud, ensure that Agent Identity is enabled. If you're deploying to Agent Runtime on Gemini Enterprise Agent Platform , use the identity_type=AGENT_IDENTITY flag:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

What's next

• Authenticate to external services using an agent's own identity
• Authenticate using 2-legged OAuth with auth manager
• Authenticate using 3-legged OAuth with auth manager
• Authenticate using API key with auth manager
• Manage Agent Identity auth providers
• Agent Identity overview