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

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

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

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é de l'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 à des services, demandez à votre administrateur de vous accorder les rôles IAM suivants sur la ressource cible : Google Cloud

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)
- Utilisateur Vertex AI (roles/aiplatform.user)
- 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 que votre agent puisse accéder à un Google Cloud service, 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 Google Cloud console ou la gcloud CLI.

Console

Dans la Google Cloud console, 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 cette ressource, puis cliquez sur l'onglet Autorisations ou IAM.
Cliquez sur Accorder l'accès.
Dans le champ Nouveaux comptes principaux, saisissez l'identifiant de 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 accorder.
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 (par exemple, storage ou bigquery). Google Cloud
RESOURCE_NAME : nom de la ressource (par exemple, nom du bucket ou ID du jeu de données).
PRINCIPAL_IDENTIFIER : identifiant 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 : ID de votre Google Cloud organisation.
PROJECT_NUMBER : numéro de votre Google Cloud projet.
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 Google Cloud bibliothèques clientes utilisent automatiquement l'identité de l'agent lorsque votre agent est déployé dans un environnement compatible Google Cloud .

L'extrait 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 l'accès contextuel

Une stratégie 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 stratégie applique une preuve de possession démontrable (DPoP) en authentifiant le jeton d'accès de l'agent. La stratégie 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 prévu et approuvé (par exemple, un conteneur Cloud Run). Cette base de référence de sécurité rend les identifiants volés non rejouables, 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 stratégie d'accès contextuel par défaut. La désactivation supprime la protection de la liaison de jetons, ce qui rend ces jetons d'accès à courte durée vulnérables au vol ou aux attaques par relecture. Par conséquent, la désactivation n'est pas recommandée.

Pour désactiver cette option, 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 effectuez un déploiement 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]"],
    },
)