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

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

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

Prima di iniziare

  1. Verifica di aver scelto il metodo di autenticazione corretto.
  2. Crea ed esegui il deployment di un agente con Agent Identity abilitato.
  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 Google Cloud servizi, 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.

Concedere l'accesso agli agenti

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

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

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

Console

  1. Nella Google Cloud console, 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 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/*
  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 Google Cloud servizio (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: l'ID dell' Google Cloud organizzazione.
  • PROJECT_NUMBER: il Google Cloud numero del progetto.
  • LOCATION: la località dell'agente (ad esempio, us-central1). (Obbligatorio solo per l'accesso di un singolo agente.)
  • ENGINE_ID: l'ID del motore di ragionamento. (Obbligatorio solo per l'accesso di un singolo agente.)
  • ROLE: il ruolo IAM che vuoi concedere.

Fare riferimento all'identità dell'agente nel codice

Le Google Cloud librerie client utilizzano automaticamente Agent Identity quando il tuo agente viene sottoposto a deployment in un ambiente supportato Google Cloud .

Il seguente snippet Python mostra come utilizzare manualmente le credenziali di Agent Identity per chiamare l'API Cloud Vision utilizzando 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) Disattivare i token associati ai certificati

Una policy di accesso sensibile al contesto gestita da Google predefinita contribuisce a proteggere le credenziali di Agent Identity. Oltre ad Agent Gateway, la policy applica la dimostrazione della prova di possesso (DPoP) autenticando il token di accesso dell'agente. La policy richiede anche mutual TLS (mTLS) per accedere ad 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 le credenziali rubate non riproducibili, contribuendo a proteggere dal furto di credenziali e dal takeover dell'account (ATO).

L'associazione ai certificati contribuisce a proteggere due tipi di credenziali dell'agente:

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

Disattivare 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 Google Cloud token di accesso sia per i token ID OIDC, rendendo questi token di breve durata vulnerabili al furto o agli attacchi di riproduzione.

Tuttavia, puoi disattivare l'associazione 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.
  • L'agente non può eseguire l'autenticazione e restituisce un 401 UNAUTHENTICATED errore.

Per disattivare l'associazione 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",
  }
}

Disattivare l'associazione per le singole richieste di token ID

Per impostazione predefinita, le librerie client di autenticazione Google supportate associano crittograficamente i token ID OIDC al certificato X.509 univoco dell'agente includendo l'impronta digitale del certificato nella rivendicazione cnf (x5t#S256) del token.

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

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 del pubblico o l'URL del servizio di ricezione chiamato dall'agente.

Eseguire il deployment dell'agente

Quando esegui il deployment dell'agente in Google Cloud, assicurati che Agent Identity sia abilitato. Se esegui il deployment in Agent Runtime su Gemini Enterprise Agent Platform , utilizza il 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]"],
    },
)

Passaggi successivi