Authentifier vos agents d'IA

Lorsque vous déployez un agent sur Cloud Run, vous pouvez lui attribuer une identité qui lui permet de s'authentifier de manière sécurisée lorsqu'il communique avec des API et d'autres agents.

S'authentifier auprès des Google Cloud API, d'autres agents et outils

Lorsque votre charge de travail Cloud Run est configurée avec le type d'identité agent-identity, elle reçoit une identité gérée par le système au format suivant :

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

Pour les projets sans organisation, le format utilise le numéro de projet :

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

Vous pouvez utiliser cette identité pour authentifier votre agent de manière sécurisée lorsqu'il communique avec Google Cloud des API, d'autres agents ou des outils.

S'authentifier auprès des Google Cloud API

Les agents peuvent utiliser leur identité d'agent attribuée pour s'authentifier auprès d' Google Cloud API telles que Vertex AI, Cloud Storage et d'autres Google Cloud produits à l'aide de jetons d'accès extraits du serveur de métadonnées Cloud Run.

  1. Attribuez le rôle IAM approprié au compte principal de votre agent, par exemple :

    • Accorder l'accès à Vertex AI :

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

    • Accorder l'accès à d'autres Google Cloud API :

      Attribuez le rôle requis sur votre ressource cible à AGENT_PRINCIPAL, par exemple, roles/storage.objectViewer sur un bucket Cloud Storage. Pour en savoir plus, consultez la section S'authentifier avec les identifiants par défaut de l'application.

    Remplacez les éléments suivants :

    • PROJECT_ID: ID de votre Google Cloud projet.
    • AGENT_PRINCIPAL: identité de votre agent, par exemple, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.

  2. Dans le code de votre application d'agent, utilisez les bibliothèques clientes Google Cloud standards. Les bibliothèques clientes utilisent automatiquement les identifiants par défaut de l'application pour extraire des jetons d'accès à courte durée de vie du serveur de métadonnées.

    Vous pouvez également extraire manuellement un jeton d'accès du serveur de métadonnées dans votre conteneur :

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

S'authentifier auprès d'autres agents sur Cloud Run

Lorsqu'un agent doit appeler un autre agent hébergé sur Cloud Run tel que les agents A2A, authentifiez-vous à l'aide d'un jeton d'identité JWT validé par la vérification IAM intégrée roles/run.invoker de Cloud Run :

  1. Attribuez le rôle roles/run.invoker à l'identité de l'agent appelant sur le service Cloud Run cible :

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

    Remplacez les éléments suivants :

    • TARGET_SERVICE_NAME: nom du service d'agent Cloud Run de destination.
    • CALLER_AGENT_PRINCIPAL: identité de l'agent appelant.
    • REGION : Google Cloud région du service cible.

Options de validation des jetons

Cloud Run est compatible avec deux méthodes de validation des jetons d'identité :

  • Jetons non liés : jetons d'identité standards liés à l'audience générés par le serveur de métadonnées. Il s'agit du mécanisme par défaut pour l'authentification de service à service et d'agent à agent.
  • Jetons liés : fournit une liaison cryptographique entre le jeton et le certificat de la charge de travail à l'aide de mTLS. Pour utiliser des jetons liés, le client appelant fournit sa chaîne de certificats feuille dans la requête.
Extraire un jeton d'ID non lié
  1. À partir du conteneur de l'agent appelant, extrayez un jeton d'identité avec l'URL du service cible comme audience : 
    TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
     Remplacez TARGET_SERVICE_URL par l'URL du service Cloud Run de destination, par exemple, https://target-agent-1234567890.us-central1.run.app.
  2. Envoyez des requêtes au service cible avec le jeton dans le Authorization en-tête : 
    curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
Extraire un jeton d'ID lié (mTLS)
  1. À partir du conteneur de l'agent appelant, lisez votre chaîne de certificats feuille et demandez un jeton lié au serveur de métadonnées à l'aide d'une requête 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. Appelez le point de terminaison mTLS du service cible en présentant les certificats de la charge de travail lors de la négociation 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
Exemple Python

Si vous écrivez du code d'agent basé sur Python, les bibliothèques clientes Google Cloud standards demandent automatiquement des jetons liés par défaut lorsque des certificats sont présents. Si vous devez effectuer des requêtes HTTP manuelles :

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)

Remplacez TARGET_SERVICE_MTLS_URL par l'URL mTLS du service Cloud Run de destination, par exemple, https://target-agent-12345.us-central1.mtls.run.app.

S'authentifier auprès des serveurs MCP sur Cloud Run

Pour vous connecter à un serveur ou à un outil MCP hébergé sur Cloud Run, utilisez l'identifiant --functional-type=mcp-server pour activer l'enregistrement automatique du serveur MCP dans l'Agent Registry.

Si votre serveur MCP n'est accessible que par d'autres agents exécutés sur Cloud Run, utilisez la vérification de l'appelant IAM intégrée. Laissez vos agents communiquer de manière native à l'aide de règles d'appelant d'exécution standards :

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

Remplacez les éléments suivants :

  • MCP_SERVICE_NAME: nom du service Cloud Run de destination hébergeant le serveur MCP.
  • CALLING_AGENT_PRINCIPAL: identité principale de l'agent appelant le serveur MCP. Par exemple, serviceAccount:my-agent@my-project.iam..
  • REGION : Google Cloud région où le serveur MCP est déployé.

Après avoir attribué le rôle run.invoker, l'agent appelant peut extraire un jeton d'identité comme décrit dans la section Options de validation des jetons.

Pour savoir comment protéger les serveurs MCP avec IAP pour l'accès CLI et l'accès SDK programmatique, consultez la section Authentifier les serveurs MCP.

S'authentifier au nom des utilisateurs

Lorsque votre agent accède à des outils et services externes au nom d'un utilisateur, il peut utiliser son identité d'agent provisionnée pour gérer l'authentification auprès des serveurs MCP et des points de terminaison externes.

Pour gérer de manière sécurisée les workflows d'autorisation complexes, tels que le consentement OAuth à trois volets (3LO), OAuth à deux volets (2LO) et les clés API, configurez le gestionnaire d'authentification des identités d'agent.

Pour obtenir des instructions sur la liaison de ces gestionnaires d'authentification à vos ensembles d'outils, consultez la section S'authentifier auprès des outils et des ressources.