Eseguire l'autenticazione in Google Cloud utilizzando l'identità dell'agente

Gli agenti possono accedere alle API Google Cloud e ad altre risorse utilizzando la propria identità. Google consiglia questo metodo per gli agenti ospitati su Google Cloud per interagire con altri servizi Google Cloud .

Quando un agente agisce di propria autorità, utilizza la sua identità SPIFFE principale per richiedere i token di accesso Google Cloud .

Prima di iniziare

  1. Verifica di aver scelto il metodo di autenticazione corretto.
  2. Crea ed esegui il deployment di un agente con l'identità dell'agente abilitata.
  3. Verifica di disporre dei ruoli necessari per completare questa attività.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per concedere a un agente l'accesso ai servizi Google Cloud , chiedi all'amministratore di concederti i seguenti ruoli IAM sulla risorsa di destinazione:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi l'accesso agli agenti

Per consentire all'agente di accedere a un servizio Google Cloud , devi concedere all'identità dell'agente i ruoli richiesti sulla risorsa di destinazione.

Nelle policy di autorizzazione IAM, le identità degli agenti utilizzano gli identificatori delle entità.

Per concedere a un agente l'accesso a una risorsa, utilizza la console Google Cloud o gcloud CLI.

Console

  1. Nella console Google Cloud , vai alla pagina IAM della risorsa a cui vuoi concedere l'accesso.
    • Per un progetto, vai alla pagina IAM:

      Vai alla pagina IAM

    • Per altre risorse, vai alla pagina della risorsa e fai clic sulla scheda Autorizzazioni o IAM.
  2. Fai clic su Concedi l'accesso.
  3. Nel campo Nuove entità, inserisci l'identificatore dell'entità che corrisponde al livello di accesso che vuoi concedere:
    • Un singolo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Tutti gli agenti in un progetto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Tutti gli agenti di un'organizzazione: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. Nel campo Seleziona un ruolo, cerca e seleziona il ruolo che vuoi concedere.
  5. Fai clic su Salva.

Google Cloud CLI

Per concedere a un agente l'accesso a una risorsa, esegui questo comando: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Sostituisci quanto segue:

  • SERVICE: il servizio Google Cloud (ad esempio, storage o bigquery).
  • RESOURCE_NAME: il nome della risorsa (ad esempio, il nome del bucket o l'ID del set di dati).
  • PRINCIPAL_IDENTIFIER: l'identificatore dell'entità che corrisponde al livello di accesso che vuoi concedere:
    • Un singolo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Tutti gli agenti di un progetto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Tutti gli agenti di un'organizzazione: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: il tuo ID organizzazione Google Cloud .
  • PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
  • LOCATION: la località dell'agente (ad esempio, us-central1). (Obbligatorio solo per l'accesso di un singolo agente.)
  • ENGINE_ID: l'ID del tuo motore di ragionamento. (Obbligatorio solo per l'accesso di un singolo agente.)
  • ROLE: il ruolo IAM che vuoi concedere.

Fai riferimento all'identità dell'agente nel codice

Le librerie client Google Cloud utilizzano automaticamente l'identità dell'agente quando viene eseguito il deployment dell'agente in un ambiente Google Cloud supportato.

Il seguente snippet Python mostra come utilizzare manualmente le credenziali dell'identità dell'agente per chiamare l'API Cloud Vision utilizzando l'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]}

(Facoltativo) Disattiva i token associati ai certificati

Una policy di accesso sensibile al contesto predefinita gestita da Google contribuisce a proteggere le credenziali di Agent Identity. Oltre all'Agent Gateway, la policy applica la dimostrazione della prova di possesso (DPoP) autenticando il token di accesso dell'agente. La policy richiede anche il mutual TLS (mTLS) per accedere all'Agent Gateway. Questo requisito contribuisce a garantire che solo l'ambiente di runtime previsto e attendibile, ad esempio un container Cloud Run o un pod Google Kubernetes Engine (GKE), possa utilizzare i token associati ai certificati. Questa baseline di sicurezza rende inutilizzabili le credenziali rubate, contribuendo a proteggere dal furto di credenziali e dal takeover dell'account (ATO).

L'associazione dei certificati aiuta a proteggere due tipi di credenziali dell'agente:

  • Token di accessoGoogle Cloud : token di accesso OAuth 2.0 di breve durata che autenticano le richieste alle API Google Cloud e ad altre risorse (*.googleapis.com).
  • Token ID OpenID Connect (OIDC): token web JSON (JWT) che autenticano le richieste ai servizi esterni e agli strumenti e ai servizi ospitati su runtime Google Cloud , come Cloud Run (*.mtls.run.app) o GKE.

Disattiva l'associazione per tutti i token di accesso e ID

La disattivazione della policy di accesso sensibile al contesto predefinita e dei token associati ai certificati nell'ambiente di runtime non è consigliata. L'impostazione di GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false rimuove la protezione dell'associazione dei token sia per i token di accesso Google Cloud sia per i token ID OIDC, rendendo questi token di breve durata vulnerabili ad attacchi di furto o replay.

Tuttavia, puoi disattivare l'opzione nell'ambiente di runtime nei seguenti rari casi:

  • Hai requisiti specifici per la condivisione dei token tra gli agenti.
  • Devi inserire il token direttamente nell'intestazione della richiesta.
  • Il tuo agente non può eseguire l'autenticazione e restituisce un errore 401 UNAUTHENTICATED.

Per disattivare la raccolta nell'ambiente di runtime, imposta la seguente variabile di ambiente quando esegui il deployment dell'agente:

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

Disattivazione per singole richieste di token ID

Per impostazione predefinita, le librerie client di autenticazione Google supportate associano in modo crittografico i token ID OIDC al certificato X.509 univoco dell'agente includendo il fingerprint del certificato nell'attestazione cnf (x5t#S256) del token.

Alcuni servizi, come Cloud Run, applicano l'associazione dei certificati quando è presente l'attestazione cnf. Se l'agente chiama questi servizi su un endpoint non mTLS, ad esempio un URL *.run.app standard, o se un endpoint di destinazione non richiede l'associazione del certificato, puoi disattivare l'opzione per le singole richieste di token ID. Questa impostazione influisce solo su quella richiesta e non disattiva l'associazione dei certificati per i token di accesso Google Cloud .

Python

Nella libreria Python google-auth (2.61.0 o versioni successive su GKE e 2.62.0 o versioni successive su Cloud Run), imposta bind_id_token=False:

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,
)

Sostituisci TARGET_SERVICE_URL con l'URI o l'URL del segmento di pubblico del servizio di ricezione chiamato dall'agente.

Esegui il deployment dell'agente

Quando esegui il deployment dell'agente in Google Cloud, assicurati che l'identità dell'agente sia abilitata. Se esegui il deployment in Agent Runtime su Gemini Enterprise Agent Platform, utilizza il flag identity_type=AGENT_IDENTITY:

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]"],
    },
)

Passaggi successivi