Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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 API, d'autres agents et des outils Google Cloud

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 du 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 des API, d'autres agents ou des outils Google Cloud .

S'authentifier auprès des API Google Cloud

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

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 API Google Cloud :
  
  Accordez 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 S'authentifier avec les identifiants par défaut de l'application.
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud .
- 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.
Dans le code de l'application de votre agent, utilisez les bibliothèques clientes Google Cloud standards. Les bibliothèques clientes utilisent automatiquement les identifiants par défaut de l'application (ADC) pour récupérer des jetons d'accès éphémères à partir du serveur de métadonnées.

Vous pouvez également récupérer manuellement un jeton d'accès à partir du serveur de métadonnées à l'intérieur de 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é JSON Web Token (JWT) validé par la vérification IAM roles/run.invoker intégrée de Cloud Run :

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 accepte 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 : fournissent 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.

Vous pouvez utiliser des jetons liés à mTLS pour appeler des ressources Cloud Run configurées avec ingress=internal. Cela vous permet de restreindre l'accès à Internet public à vos agents ou serveurs MCP sans nécessiter de réseau VPC.

Récupérer un jeton d'identité non lié

À partir du conteneur de l'agent appelant, récupérez 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.
Envoyez des requêtes au service cible avec le jeton dans l'en-tête Authorization :
```
curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
```

Récupérer un jeton d'identité lié (mTLS)

Dans le 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")

Appelez le point de terminaison mTLS du service cible en présentant les certificats de charge de travail lors du 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

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 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. Permettez à vos agents de communiquer de manière native à l'aide de règles d'appel 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 qui héberge le serveur MCP.
CALLING_AGENT_PRINCIPAL : identité principale de l'agent qui appelle le serveur MCP. Exemple : serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com.
REGION : région Google Cloud dans laquelle le serveur MCP est déployé.

Après avoir attribué le rôle run.invoker, l'agent appelant peut récupérer 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 SDK programmatique, consultez 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 avec les serveurs MCP et les points de terminaison externes.

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

Pour savoir comment associer ces gestionnaires d'authentification à vos ensembles d'outils, consultez S'authentifier auprès des outils et des ressources.