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 Cloudafin d'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

  1. Vérifiez que vous avez choisi la bonne méthode d'authentification.
  2. Créez et déployez un agent avec l'identité de l'agent activée.
  3. 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 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 compte principal.

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

Console

  1. 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 correspondante, puis cliquez sur l'onglet Autorisations ou IAM.
  2. Cliquez sur Accorder l'accès.
  3. Dans le champ Nouveaux comptes principaux, saisissez l'identifiant du compte principal correspondant 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/*
  4. Dans le champ Sélectionner un rôle, recherchez et sélectionnez le rôle que vous souhaitez accorder.
  5. 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, nom du bucket ou ID de l'ensemble de données).
  • PRINCIPAL_IDENTIFIER : identifiant du compte principal correspondant 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 : 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 accorder.

Faire référence à 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 Agent Identity 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 l'accès contextuel

Une règle d'accès contextuel par défaut gérée par Google permet de sécuriser les identifiants Agent Identity. Au-delà d'Agent Gateway, la règle applique la preuve de possession (DPoP) en authentifiant le jeton d'accès de l'agent. La règle exige également l'authentification TLS mutuelle (mTLS) pour accéder à Agent Gateway. Cette exigence garantit que les jetons liés à un certificat ne peuvent être utilisés que depuis leur environnement d'exécution fiable prévu (par exemple, un conteneur Cloud Run). 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.

Dans de rares cas, par exemple en cas d'exigences spécifiques de partage de jetons entre les agents, si vous devez injecter le jeton directement dans l'en-tête ou si votre agent ne peut pas s'authentifier avec une erreur 401 UNAUTHENTICATED, vous pouvez désactiver la règle d'accès contextuel par défaut. Si vous désactivez cette option, la protection de l'association de jetons est supprimée, ce qui rend ces jetons d'accès éphémères vulnérables au vol ou aux attaques par relecture. Nous vous déconseillons donc de désactiver cette fonctionnalité.

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

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

Déployer l'agent

Lorsque vous déployez votre agent sur Google Cloud, assurez-vous que l'identité de l'agent est activée. Si vous déployez sur Agent Runtime sur Gemini Enterprise Agent Platform , utilisez l'indicateur 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]"],
    },
)

Étapes suivantes