Autenticare gli agenti AI

Quando esegui il deployment di un agente su Cloud Run, puoi assegnargli un'identità che gli consenta di autenticarsi in modo sicuro quando comunica con le API e altri agenti.

Autenticazione nelle Google Cloud API, in altri agenti e strumenti

Quando il carico di lavoro di Cloud Run è configurato con il tipo di identità agent-identity, riceve un'identità gestita dal sistema nel seguente formato:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Per i progetti senza un'organizzazione, il formato utilizza il numero di progetto:

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Puoi utilizzare questa identità per autenticare in modo sicuro il tuo agente quando comunica con le Google Cloud API, altri agenti o strumenti.

Autenticazione nelle Google Cloud API

Gli agenti possono utilizzare la loro identità agente assegnata per autenticarsi nelle Google Cloud API come Vertex AI, Cloud Storage e altri Google Cloud prodotti utilizzando i token di accesso recuperati dal server di metadati di Cloud Run.

  1. Concedi il ruolo IAM appropriato all'entità del tuo agente, ad esempio:

    • Concedi l'accesso a Vertex AI:

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"

    • Concedi l'accesso ad altre Google Cloud API:

      Concedi il ruolo richiesto alla risorsa di destinazione a AGENT_PRINCIPAL, ad esempio roles/storage.objectViewer su un bucket Cloud Storage. Per i dettagli, consulta Autenticazione con le credenziali predefinite dell'applicazione.

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • AGENT_PRINCIPAL: l'identità del tuo agente, ad esempio principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.

  2. Nel codice dell'applicazione dell'agente, utilizza le librerie client standard di Google Cloud. Le librerie client utilizzano automaticamente le credenziali predefinite dell'applicazione (ADC) per recuperare i token di accesso di breve durata dal server di metadati.

    In alternativa, puoi recuperare manualmente un token di accesso dal server di metadati all'interno del container:

    curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"

Autenticazione in altri agenti su Cloud Run

Quando un agente deve chiamare un altro agente ospitato su Cloud Run ad esempio gli agenti A2A, esegui l'autenticazione utilizzando un token JWT (JSON Web Token) con identità convalidato dal controllo IAM roles/run.invoker integrato di Cloud Run:

  1. Concedi all'identità dell'agente chiamante il ruolo roles/run.invoker nel servizio Cloud Run di destinazione:

    gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

    Sostituisci quanto segue:

    • TARGET_SERVICE_NAME: il nome del servizio agente Cloud Run di destinazione.
    • CALLER_AGENT_PRINCIPAL: l'identità dell'agente chiamante.
    • REGION: la Google Cloud regione del servizio di destinazione.

Opzioni di convalida dei token

Cloud Run supporta due metodi di convalida dei token di identità:

  • Token non associati: token di identità standard associati al pubblico generati dal server di metadati. Questo è il meccanismo predefinito per l'autenticazione da servizio a servizio e da agente ad agente.
  • Token associati: fornisce l'associazione crittografica tra il token e il certificato del carico di lavoro utilizzando mTLS. Per utilizzare i token associati, il client chiamante fornisce la catena di certificati foglia nella richiesta.
Recupera un token ID non associato
  1. Dal container dell'agente chiamante, recupera un token di identità con l'URL del servizio di destinazione come pubblico: 
    TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
     Sostituisci TARGET_SERVICE_URL con l'URL del servizio Cloud Run di destinazione, ad esempio, https://target-agent-1234567890.us-central1.run.app.
  2. Invia richieste al servizio di destinazione con il token nell' Authorization intestazione: 
    curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
Recupera un token ID associato (mTLS)
  1. Dal container dell'agente chiamante, leggi la catena di certificati foglia e richiedi un token associato dal server di metadati utilizzando una richiesta POST: 
    CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")
  2. Chiama l'endpoint mTLS del servizio di destinazione, presentando i certificati del carico di lavoro durante l'handshake TLS: 
    KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint
Esempio Python

Se scrivi codice agente basato su Python, le librerie client standard di Google Cloud richiedono automaticamente i token associati per impostazione predefinita quando sono presenti i certificati. Se devi effettuare richieste HTTP manuali:

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

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

Sostituisci TARGET_SERVICE_MTLS_URL con l'URL mTLS del servizio Cloud Run di destinazione, ad esempio https://target-agent-12345.us-central1.mtls.run.app.

Autenticazione nei server MCP su Cloud Run

Per connetterti a un server o a uno strumento MCP ospitato su Cloud Run, utilizza l'identificatore --functional-type=mcp-server per attivare la registrazione automatica del server MCP in Agent Registry.

Se al server MCP accedono solo altri agenti in esecuzione su Cloud Run, utilizza il controllo dell'invoker IAM integrato. Consenti agli agenti di comunicare in modo nativo utilizzando le norme standard dell'invoker di esecuzione:

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

Sostituisci quanto segue:

  • MCP_SERVICE_NAME: il nome del servizio Cloud Run di destinazione che ospita il server MCP.
  • CALLING_AGENT_PRINCIPAL: l'identità principale dell'agente che richiama il server MCP. Ad esempio, serviceAccount:my-agent@my-project.iam..
  • REGION: la Google Cloud regione in cui viene eseguito il deployment del server MCP.

Dopo aver concesso il ruolo run.invoker, l'agente chiamante può recuperare un token di identità come descritto nella sezione Opzioni di convalida dei token.

Per scoprire come proteggere i server MCP con IAP per l'accesso programmatico e alla CLI, consulta Autenticare i server MCP.

Autenticazione per conto degli utenti

Quando l'agente accede a strumenti e servizi esterni per conto di un utente, può utilizzare la sua identità agente di cui è stato eseguito il provisioning per gestire l'autenticazione con i server MCP e gli endpoint esterni.

Per gestire in modo sicuro i flussi di lavoro di autorizzazione complessi, come il consenso OAuth a 3 passaggi (3LO), OAuth a 2 passaggi (2LO) e le chiavi API, configura il Agent Identity Auth Manager.

Per istruzioni su come associare questi gestori dell'autenticazione ai tuoi toolset, consulta Autenticazione a strumenti e risorse.