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 à partir d'un agent. Clés API Vérifiez que l'API que vous souhaitez utiliser est compatible avec les clés API avant d'utiliser cette méthode d'authentification.
Gérer les comptes utilisateur, l'enregistrement, la connexion ou l'autorisation pour les utilisateurs finaux de l'agent ID client OAuth Nécessite que votre agent demande et reçoive le consentement de l'utilisateur.

Rôles

Les agents que vous déployez sur Agent Engine s'exécutent à l'aide du compte de service Agent de service AI Platform Reasoning Engine correspondant à service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Le compte de service dispose d'un rôle (roles/aiplatform.reasoningEngineServiceAgent) Agent de service Reasoning Engine Vertex AI 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 et cochez la case "Inclure les attributions de rôles fournies par Google".

    Accéder à IAM

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

  3. Recherchez le compte principal correspondant à service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

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

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 généré lorsque l'agent est déployé sur 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

Authentifiez-vous, puis exécutez la commande suivante pour afficher 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)

Dans cette commande, PRINCIPAL est basé sur le compte de service généré lorsque l'agent est déployé sur Agent Engine.

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

  1. Accédez à la page IAM et cochez la case "Inclure les attributions de rôles fournies par Google".

    Accéder à IAM

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

  3. Recherchez le compte principal correspondant à service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  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.

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 généré lorsque l'agent est déployé sur Agent Engine.
  • ROLE_NAME est le nom du rôle que vous souhaitez accorder. 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 le contrôle des accès IAM de manière programmatique. Si vous le souhaitez ou si vous devez le faire en Python, consultez la documentation de la bibliothèque cliente IAM.

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

  1. Accédez à la page IAM et cochez la case "Inclure les attributions de rôles fournies par Google".

    Accéder à IAM

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

  3. Recherchez le compte principal correspondant à service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  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.

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 généré lorsque l'agent est déployé sur Agent Engine.
  • ROLE_NAME est le 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 le contrôle des accès IAM de manière programmatique. Si vous le souhaitez ou si vous 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 lors de la création de ce dernier, 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 sa 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 du secret ou l'identifiant complet du secret.
  • FILE_PATH est le chemin d'accès complet (y compris le nom de fichier) au fichier contenant les informations sur la version.

Pour en savoir plus, consultez la documentation de Secret Manager pour créer un secret et une version de secret, ou la documentation de référence de la CLI pour créer un secret et 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 sa valeur correspondante, par exemple Location:asia-east1.

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

  5. (Facultatif) Pour filtrer les versions de 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 répertorier 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 des expressions régulières (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 du secret ou l'identifiant complet du secret.

Pour en savoir plus, consultez la documentation de Secret Manager pour filtrer les secrets et lister les versions de secrets, ou la documentation de référence de la CLI pour lister les secrets et les 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é d'étiquette, et
  • VALUE est la valeur correspondante du libellé.

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.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 de secret, exécutez la commande suivante:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

Où :

  • VERSION_ID est le nom de la ressource de la version du secret, et
  • 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 de Secret Manager sur la suppression d'un secret et la destruction d'une version de secret, ou la documentation de référence de la 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 des identifiants OAuth.

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

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

Créer un identifiant client OAuth

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

    Accéder à Google Auth Platform > Clients

  2. (Si nécessaire) Si l'écran indique "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 la page 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 de REDIRECT_URI.

  7. Sous "Codes secrets du client", cliquez sur le bouton "Télécharger le fichier JSON". Il télécharge un fichier client_secret.json contenant le contenu suivant:

{'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 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),
    },
})

Répertorier les clients OAuth

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

    Accéder à Google Auth Platform > Clients

  2. La liste des identifiants client OAuth dont vous disposez s'affiche.

Supprimer un client OAuth

  1. Dans la console Google Cloud, accédez à la page Google Auth Platform > Clients (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".