Gérer l'accès des agents déployés

Différents types de méthodes d'authentification sont disponibles pour différents modes d'accès :

Cas d'utilisation	Méthode d'authentification	À propos de cette méthode d'authentification
Accédez aux sources de données directement depuis un agent.	Compte de service	Les agents déployés ont accès à toutes les ressources auxquelles leur compte de service est autorisé à accéder.
Envoyez des requêtes aux points de terminaison à l'aide de clés API depuis un agent.	Clés API	Avant d'utiliser cette méthode d'authentification, vérifiez que l'API que vous souhaitez utiliser est compatible avec les clés API.
Gérez les comptes utilisateur, l'inscription, la connexion ou l'autorisation pour les utilisateurs finaux de l'agent.	ID client OAuth	Votre agent doit demander et obtenir le consentement de l'utilisateur.

Rôles

Les agents que vous déployez sur Vertex AI Agent Engine s'exécutent à l'aide de l'agent de service AI Platform Reasoning Engine ou de votre compte de service personnalisé. Pour en savoir plus, consultez Configurer l'identité et les autorisations de votre agent.

Agent de service AI Platform Reasoning Engine

Le compte de service Agent de service AI Platform Reasoning Engine utilise le format [e-mail].

Le compte de service dispose d'un rôle Agent de service Vertex AI Reasoning Engine (roles/aiplatform.reasoningEngineServiceAgent) qui accorde les autorisations par défaut requises pour les agents déployés. Vous pouvez consulter la liste complète des autorisations par défaut dans la documentation IAM.

Lister les rôles d'un agent déployé

Console

1. Accédez à la page IAM.

   Accéder à IAM

2. Sélectionnez le projet correspondant à votre projet Google Cloud .

3. Recherchez le principal qui correspond au compte de service utilisé comme identité de votre agent.

4. Les rôles de l'agent déployé se trouvent dans la colonne Rôle.

Remarque : Pour le compte de service Agent de service AI Platform Reasoning Engine, vous devez sélectionner "Inclure les attributions de rôles fournies par Google" pour afficher le compte de service dans le tableau des principaux.

gcloud

Commencez par installer et initialiser la CLI gcloud. Exécutez ensuite la commande suivante :

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

Où :

• PROJECT_ID_OR_NUMBER correspond à l'ID ou au numéro de votre projet.
• PRINCIPAL est basé sur le compte de service utilisé lors du déploiement de l'agent sur Vertex AI Agent Engine.

Pour en savoir plus, consultez la documentation IAM et la documentation de référence de la CLI.

Python

Commencez par installer la bibliothèque cliente en exécutant

pip install google-api-python-client

Ensuite, authentifiez-vous et exécutez la commande suivante pour lister les rôles d'un agent déployé :

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

Où PRINCIPAL est basé sur le compte de service utilisé lors du déploiement de l'agent sur Vertex AI Agent Engine.

Attribuer des rôles pour un agent déployé

Console (recommandé)

1. Accédez à la page IAM.

   Accéder à IAM

2. Sélectionnez le projet correspondant à votre projet Google Cloud .

3. Recherchez le principal qui correspond au compte de service utilisé comme identité de votre agent.

4. Ajoutez les rôles requis au compte principal en cliquant sur le bouton de modification, en ajoutant les rôles, puis en cliquant sur le bouton d'enregistrement.

Remarque : Pour le compte de service Agent de service AI Platform Reasoning Engine, vous devez sélectionner "Inclure les attributions de rôles fournies par Google" pour afficher le compte de service dans le tableau des principaux.

gcloud

Commencez par installer et initialiser la CLI gcloud. Exécutez ensuite la commande suivante :

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

Où :

• PRINCIPAL est basé sur le compte de service utilisé lors du déploiement de l'agent sur Vertex AI Agent Engine.
• ROLE_NAME : nom du rôle que vous souhaitez attribuer. Pour obtenir la liste complète des rôles prédéfinis, consultez la page Comprendre les rôles.

Pour en savoir plus, consultez la documentation IAM et la documentation de référence de la CLI.

Python

Nous vous déconseillons d'écrire votre propre code Python pour accorder ou révoquer des rôles pour les agents déployés. Nous vous recommandons plutôt d'utiliser la console Google Cloud ou gcloud pour les opérations ponctuelles, ou Terraform pour gérer contrôle des accès IAM de manière programmatique. Si vous souhaitez ou devez le faire en Python, consultez la documentation de la bibliothèque cliente IAM.

Révoquer des rôles d'un agent déployé

Console (recommandé)

1. Accédez à la page IAM.

   Accéder à IAM

2. Sélectionnez le projet correspondant à votre projet Google Cloud .

3. Recherchez le principal qui correspond au compte de service utilisé comme identité de votre agent.

4. Révoquez les rôles du compte principal en cliquant sur le bouton de modification, en supprimant les rôles correspondants, puis en cliquant sur le bouton d'enregistrement.

Remarque : Pour le compte de service Agent de service AI Platform Reasoning Engine, vous devez sélectionner "Inclure les attributions de rôles fournies par Google" pour afficher le compte de service dans le tableau des principaux.

gcloud

Commencez par installer et initialiser la CLI gcloud. Exécutez ensuite la commande suivante :

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

Où :

• PRINCIPAL est basé sur le compte de service utilisé lors du déploiement de l'agent sur Vertex AI Agent Engine.
• ROLE_NAME : nom du rôle que vous souhaitez révoquer. Pour obtenir la liste complète des rôles prédéfinis, consultez la page Comprendre les rôles.

Pour en savoir plus, consultez la documentation IAM et la documentation de référence de la CLI.

Python

Nous vous déconseillons d'écrire votre propre code Python pour accorder ou révoquer des rôles pour les agents déployés. Nous vous recommandons plutôt d'utiliser la console Google Cloud ou gcloud pour les opérations ponctuelles, ou Terraform pour gérer contrôle des accès IAM de manière programmatique. Si vous souhaitez ou devez le faire en Python, consultez la documentation de la bibliothèque cliente IAM.

Secrets

Un secret contient une ou plusieurs versions de secret, ainsi que des métadonnées telles que des étiquettes et des informations de réplication. La charge utile réelle d'un secret est stockée dans une version de secret. Les secrets sont gérés (via Secret Manager) au niveau du projet et peuvent être partagés entre les agents déployés. Pour lister les secrets correspondant à un agent dans Secret Manager, vous pouvez ajouter des libellés et les utiliser pour filtrer.

Créer un secret

Console

1. Accédez à la page Secret Manager.

   Accéder à Secret Manager

2. Sur la page Secret Manager, cliquez sur Créer un secret.

3. Dans le champ Nom, saisissez un nom pour le secret (par exemple, my-secret).

4. Facultatif : Pour ajouter une version de secret au moment de sa création, saisissez une valeur dans le champ Valeur du secret (par exemple, abcd1234).

5. Accédez à Libellés, puis cliquez sur Ajouter un libellé.

6. Saisissez une clé et la valeur correspondante pour créer un libellé.

7. Cliquez sur Créer un secret.

gcloud

Commencez par installer et initialiser la CLI gcloud. Exécutez ensuite les commandes suivantes :

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

Où :

• SECRET_ID est l'ID ou l'identifiant complet du secret.
• FILE_PATH est le chemin d'accès complet (y compris le nom du fichier) au fichier contenant les informations sur la version.

Pour en savoir plus, consultez la documentation Secret Manager sur la création d'un secret et d'une version de secret, ou la documentation de référence de la CLI sur la création d'un secret et d'une version de secret, respectivement.

Python

Commencez par installer la bibliothèque cliente en exécutant

pip install google-cloud-secret-manager

Ensuite, authentifiez-vous et exécutez la commande suivante :

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

Obtenir un secret

Console

1. Accédez à la page Secret Manager.

   Accéder à Secret Manager

2. Sur la page Secret Manager, cliquez sur le nom d'un secret à décrire.

3. La page Informations détaillées sur le secret répertorie les informations sur le secret.

gcloud

Commencez par installer et initialiser la CLI gcloud. Exécutez ensuite la commande suivante :

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

Où :

• VERSION_ID est l'ID de la version du secret.
• SECRET_ID est l'ID du secret ou l'identifiant complet du secret.

Pour en savoir plus, consultez la documentation de Secret Manager ou la documentation de référence de la CLI.

Python

Commencez par installer la bibliothèque cliente en exécutant

pip install google-cloud-secret-manager

Ensuite, authentifiez-vous et exécutez la commande suivante :

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

Répertorier les secrets

Console

1. Accédez à la page Secret Manager.

   Accéder à Secret Manager

2. Dans le tableau "Secrets", cliquez dans le champ Filtre.

3. Choisissez une propriété de filtre et la valeur correspondante, par exemple Location:asia-east1.

4. Le tableau est automatiquement filtré en fonction des valeurs saisies.

5. (Facultatif) Pour filtrer les versions d'un secret, sélectionnez un secret pour accéder à ses versions, puis utilisez l'option Filtrer dans le tableau Versions.

gcloud

Commencez par installer et initialiser la CLI gcloud.

Pour lister tous les secrets d'un projet, exécutez la commande suivante :

gcloud secrets list --filter="FILTER"

où FILTER est une chaîne (par exemple, name:asecret OR name:bsecret) ou une expression régulière (par exemple, name ~ "secret_ab.*").

Pour lister toutes les versions d'un secret, exécutez la commande suivante :

gcloud secrets versions list SECRET_ID

où SECRET_ID est l'ID ou l'identifiant complet du secret.

Pour en savoir plus, consultez la documentation Secret Manager sur le filtrage des secrets et la liste des versions de secrets, ou la documentation de référence de la CLI sur la liste des secrets et des versions de secrets, respectivement.

Python

Commencez par installer la bibliothèque cliente en exécutant

pip install google-cloud-secret-manager

Ensuite, authentifiez-vous et exécutez la commande suivante :

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

Mettre à jour un secret

Console

1. Accédez à la page Secret Manager.

   Accéder à Secret Manager

2. Sur la page Secret Manager, cochez la case située à côté du nom du secret.

3. Si le panneau d'informations est fermé, cliquez sur Afficher le panneau d'informations pour afficher celui-ci.

4. Dans le panneau d'informations, cliquez sur l'onglet Libellés.

5. Cliquez sur Ajouter un libellé, puis saisissez une clé et une valeur pour le libellé.

6. Cliquez sur Enregistrer.

gcloud

Commencez par installer et initialiser la CLI gcloud. Exécutez ensuite la commande suivante :

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

Où :

• SECRET_ID est l'ID du secret ou l'identifiant complet du secret.
• KEY est la clé du libellé.
• VALUE est la valeur correspondante du libellé.

Pour en savoir plus, consultez la documentation Secret Manager ou la documentation de référence de la CLI.

Python

Commencez par installer la bibliothèque cliente en exécutant

pip install google-cloud-secret-manager

Ensuite, authentifiez-vous et exécutez la commande suivante :

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

Supprimer un secret

Console

1. Accédez à la page Secret Manager.

   Accéder à Secret Manager

2. Sur la page Secret Manager, cliquez sur Afficher plus dans la colonne Actions du secret.

3. Sélectionnez Supprimer dans le menu.

4. Saisissez le nom du secret dans la boîte de dialogue Supprimer le secret.

5. Cliquez sur le bouton Supprimer le secret.

gcloud

Commencez par installer et initialiser la CLI gcloud.

Pour supprimer une version secrète, exécutez la commande suivante :

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

Où :

• VERSION_ID est le nom de ressource de la version secrète.
• SECRET_ID est l'ID du secret ou l'identifiant complet du secret.

Pour supprimer un secret et toutes ses versions, exécutez la commande suivante :

gcloud secrets delete SECRET_ID

où SECRET_ID est l'ID du secret ou l'identifiant complet du secret.

Pour en savoir plus, consultez la documentation Secret Manager sur la suppression d'un secret et la destruction d'une version de secret, ou la référence de CLI sur la suppression d'un secret et la destruction d'une version de secret.

Python

Commencez par installer la bibliothèque cliente en exécutant

pip install google-cloud-secret-manager

Ensuite, authentifiez-vous et exécutez la commande suivante :

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

Clients et identifiants OAuth

Un ID client sert à identifier un agent unique auprès des serveurs OAuth de Google. Si votre agent s'exécute sur plusieurs plates-formes, chacune d'elle devra posséder son propre ID client. De manière générale, pour intégrer un agent basé sur OAuth, procédez comme suit :

1. Créez un client et un identifiant OAuth.

2. Stockez l'ID client et le code secret dans Secret Manager. (voir Créer un secret).

3. Accédez au secret dans votre agent pendant le développement.

Remarque : Pour en savoir plus, consultez Configurer OAuth 2.0. En savoir plus sur les types de clients OAuth

Créer un identifiant client OAuth

1. Dans la console Google Cloud , accédez à la page Google Auth Platform > Clients.

   Accéder à Google Auth Platform > Clients

2. (Si nécessaire) Si l'écran affiche "Google Auth Platform pas encore configuré", cliquez sur Commencer et remplissez les configurations du projet. (Vous pourrez les modifier ultérieurement.) Pour en savoir plus sur la préparation à la production, consultez Conformité avec les règles OAuth 2.0.

3. Cliquez sur Créer un client.

4. Définissez le paramètre Type d'application sur Web application.

5. Définissez le nom du client OAuth sur OAUTH_CLIENT_DISPLAY_NAME.

6. Sous URI de redirection autorisés, ajoutez l'URI pour REDIRECT_URI.

7. Sous "Codes secrets du client", cliquez sur le bouton "Télécharger JSON". Un fichier client_secret.json contenant les éléments suivants sera téléchargé :

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}

1. Stockez l'ID client et le code secret dans Secret Manager, par exemple.

from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

Remarque : Vous pouvez vérifier que les identifiants du client OAuth ont été stockés dans Secret Manager via la Google Cloud console.

Répertorier les clients OAuth

1. Dans la console Google Cloud , accédez à la page Google Auth Platform > Clients.

   Accéder à Google Auth Platform > Clients

2. La liste des identifiants client OAuth s'affiche.

Supprimer un client OAuth

1. Dans la console Google Cloud , accédez à la page Google Auth Platform > Clients.

   Accéder à Google Auth Platform > Clients

2. Sélectionnez le ou les identifiants de client OAuth à supprimer, puis cliquez sur "Supprimer".

Clés de chiffrement gérées par le client (CMEK)

Par défaut, Google Cloud chiffre automatiquement les données au repos à l'aide de clés de chiffrement gérées par Google. Si vous avez des exigences réglementaires ou de conformité spécifiques concernant les clés qui protègent vos données, vous pouvez utiliser des clés de chiffrement gérées par le client (CMEK) pour vos agents déployés.

Consultez la documentation CMEK pour Vertex AI pour connaître les exigences générales et obtenir des conseils sur l'utilisation de CMEK avec Vertex AI, y compris :

• Configuration du projet (facturation et API activées)
• Créer des trousseaux de clés et des clés
• Autorisations requises

Pour activer CMEK pour votre agent, vous devez spécifier encryption_spec avec votre clé Cloud KMS lorsque vous créez une instance Agent Engine. Pour obtenir des exemples de code, consultez Configurer des clés de chiffrement gérées par le client.

Limites

Les limites suivantes s'appliquent lorsque vous utilisez CMEK avec Vertex AI Agent Engine :

• Les clés multirégionales ne sont pas autorisées : seules les clés spécifiques à une région sont acceptées. La région du trousseau de clés et de la clé doit être la même que celle de votre instance Agent Engine.

• Les instances CMEK déployées ne peuvent pas être mises à jour : une fois qu'un agent est déployé avec une clé CMEK, l'instance ne peut pas être mise à jour ni modifiée pour ce déploiement. Pour utiliser une spécification Agent Engine différente (pour une nouvelle clé ou pour d'autres configurations), vous devez déployer une nouvelle instance Agent Engine.

• Certaines métadonnées et données opérationnelles ne sont pas chiffrées : CMEK chiffre les données principales de l'agent au repos. Toutefois, certaines métadonnées et données opérationnelles d'exécution ne sont pas chiffrées. Par exemple :

  • Métadonnées de l'agent :
    • Noms à afficher
    • Descriptions
  • Données opérationnelles de l'environnement d'exécution :
    • Adresses e-mail du compte de service
    • Noms des méthodes de classe d'objet d'agent
    • Variables d'environnement