S'authentifier à l'aide de la propre autorité d'un agent

Les agents peuvent accéder aux API Google Cloud et à d'autres ressources en utilisant leur propre autorité. Nous recommandons 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 attribuer.
  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 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 attribuer.

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 d'identité de l'agent. Au-delà de la passerelle d'agent, la règle applique la preuve démontrable de possession (DPoP) en authentifiant le jeton d'accès de l'agent. La règle impose également l'utilisation de mTLS pour accéder à la passerelle d'agent. Cela 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 si les agents ont des exigences spécifiques concernant le partage de jetons, 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 fonctionnalité, la protection de l'association de jetons est supprimée, ce qui rend ces jetons d'accès de courte durée 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_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": 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, 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