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.

S'authentifier auprès de Google Cloud à l'aide de la propre identité d'un agent

Les agents peuvent accéder aux API Google Cloud et à d'autres ressources en utilisant leur propre identité. Google recommande cette méthode pour les agents hébergés sur Google Cloudpour interagir avec d'autres services Google Cloud .

Lorsqu'un agent agit de sa propre autorité, il utilise son identité SPIFFE principale pour demander des jetons d'accès Google Cloud .

Avant de commencer

Vérifiez que vous avez choisi la bonne méthode d'authentification.
Créez et déployez un agent avec l'identité d'agent activée.
Vérifiez que vous disposez des rôles requis pour effectuer cette tâche.

Rôles requis

Pour obtenir les autorisations nécessaires pour accorder à un agent l'accès aux services Google Cloud , demandez à votre administrateur de vous accorder les rôles IAM suivants sur la ressource cible :

Pour accorder l'accès à un agent :
- Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
- Administrateur de sécurité (roles/iam.securityAdmin)
Rôles recommandés pour l'identité de l'agent :
- Éditeur de contexte d'agent (roles/aiplatform.agentContextEditor)
- Accès par défaut de l'agent (roles/aiplatform.agentDefaultAccess)
- Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)
- Navigateur (roles/browser)
- Lecteur des objets Storage (roles/storage.objectViewer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Accorder l'accès aux agents

Pour permettre à votre agent d'accéder à un service Google Cloud , vous devez accorder à l'identité de l'agent les rôles requis sur la ressource cible.

Dans les stratégies d'autorisation IAM, les identités d'agent utilisent des identifiants de comptes principaux.

Pour accorder à un agent l'accès à une ressource, utilisez la console Google Cloud ou gcloud CLI.

Console

Dans la console Google Cloud , accédez à la page IAM de la ressource à laquelle vous souhaitez accorder l'accès.
- Pour un projet, accédez à la page IAM :
  Accéder à la page IAM
- Pour les autres ressources, accédez à la page de la ressource concernée, puis cliquez sur l'onglet Autorisations ou IAM.
Cliquez sur Accorder l'accès.
Dans le champ Nouveaux comptes principaux, saisissez l'identifiant du compte principal qui correspond au niveau d'accès que vous souhaitez accorder :
- Un seul agent : principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Tous les agents d'un projet : principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Tous les agents d'une organisation : principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
Dans le champ Sélectionner un rôle, recherchez et sélectionnez le rôle que vous souhaitez attribuer.
Cliquez sur Enregistrer.

Google Cloud CLI

Pour accorder à un agent l'accès à une ressource, exécutez la commande suivante :

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Remplacez les éléments suivants :

SERVICE : service Google Cloud (par exemple, storage ou bigquery).
RESOURCE_NAME : nom de la ressource (par exemple, le nom du bucket ou l'ID de l'ensemble de données).
PRINCIPAL_IDENTIFIER : identifiant du compte principal qui correspond au niveau d'accès que vous souhaitez accorder :
- Un seul agent : principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Tous les agents d'un projet : principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Tous les agents d'une organisation : principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID : l'ID de votre organisation Google Cloud .
PROJECT_NUMBER : numéro de votre projet Google Cloud .
LOCATION : emplacement de votre agent (par exemple, us-central1). (Obligatoire uniquement pour l'accès à un seul agent.)
ENGINE_ID : ID de votre moteur de raisonnement. (Obligatoire uniquement pour l'accès à un seul agent.)
ROLE : rôle IAM que vous souhaitez attribuer.

Référencer l'identité de l'agent dans votre code

Les bibliothèques clientes Google Cloud utilisent automatiquement l'identité de l'agent lorsque votre agent est déployé dans un environnement Google Cloud compatible.

L'extrait de code Python suivant montre comment utiliser manuellement les identifiants d'identité de l'agent pour appeler l'API Cloud Vision à l'aide de 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]}

Facultatif : Désactiver les jetons liés à un certificat

Une règle d'accès contextuel par défaut gérée par Google permet de sécuriser les identifiants d'identité de l'agent. Au-delà d'Agent Gateway, la stratégie applique la démonstration de preuve de possession (DPoP) en authentifiant le jeton d'accès de l'agent. La stratégie nécessite également l'authentification TLS mutuelle (mTLS) pour accéder à Agent Gateway. Cette exigence permet de s'assurer que seul l'environnement d'exécution prévu et de confiance, tel qu'un conteneur Cloud Run ou un pod Google Kubernetes Engine (GKE), peut utiliser les jetons liés à un certificat. Cette référence de sécurité rend les identifiants volés inutilisables, ce qui permet de se protéger contre le vol d'identifiants et la prise de contrôle de compte.

La liaison de certificat permet de protéger deux types d'identifiants d'agent :

Jetons d'accèsGoogle Cloud : jetons d'accès OAuth 2.0 de courte durée qui authentifient les requêtes adressées aux API Google Cloud et à d'autres ressources (*.googleapis.com).
Jetons d'ID OpenID Connect (OIDC) : jetons Web JSON (JWT) qui authentifient les requêtes adressées à des services externes, ainsi qu'à des outils et services hébergés sur des environnements d'exécution Google Cloud , tels que Cloud Run (*.mtls.run.app) ou GKE.

Désactiver la liaison pour tous les jetons d'accès et d'ID

Il n'est pas recommandé de désactiver la règle d'accès contextuel par défaut et les jetons liés à un certificat dans l'environnement d'exécution. La définition de GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false supprime la protection par liaison de jeton pour les jetons d'accès Google Cloud et les jetons d'ID OIDC, ce qui rend ces jetons éphémères vulnérables aux attaques par vol ou par relecture.

Toutefois, vous pouvez désactiver cette option dans l'environnement d'exécution dans les rares cas suivants :

Vous avez des exigences spécifiques concernant le partage de jetons entre les agents.
Vous devez injecter le jeton directement dans l'en-tête de requête.
Votre agent ne peut pas s'authentifier et renvoie une erreur 401 UNAUTHENTICATED.

Pour désactiver cette fonctionnalité dans l'environnement d'exécution, définissez la variable d'environnement suivante lorsque vous déployez votre agent :

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

Désactiver pour des demandes de jeton d'ID spécifiques

Par défaut, les bibliothèques clientes Google Auth compatibles lient de manière cryptographique les jetons d'ID OIDC au certificat X.509 unique de l'agent en incluant l'empreinte du certificat dans la revendication cnf (x5t#S256) du jeton.

Certains services, tels que Cloud Run, appliquent la liaison de certificat lorsque la revendication cnf est présente. Si votre agent appelle ces services via un point de terminaison non mTLS, tel qu'une URL *.run.app standard, ou si un point de terminaison cible ne nécessite pas de liaison de certificat, vous pouvez désactiver les requêtes de jeton d'ID individuelles. Ce paramètre n'affecte que cette requête et ne désactive pas la liaison de certificat pour les jetons d'accès Google Cloud .

Python

Dans la bibliothèque Python google-auth (2.61.0 ou version ultérieure sur GKE et 2.62.0 ou version ultérieure sur Cloud Run), définissez 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,
)

Remplacez TARGET_SERVICE_URL par l'URI ou l'URL d'audience du service de réception appelé par votre agent.

Déployer l'agent

Lorsque vous déployez votre agent sur Google Cloud, assurez-vous qu'Agent Identity est activé. Si vous effectuez un déploiement sur Agent Runtime sur Gemini Enterprise Agent Platform, utilisez l'option 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]"],
    },
)