Contrôler l'accès à la banque de mémoire avec des conditions IAM

Par défaut, les autorisations Identity and Access Management de la mémoire sont définies au niveau du projet. Ce document explique comment utiliser les conditions IAM pour contrôler plus précisément l'accès aux ressources de la banque de mémoire Vertex AI Agent Engine.

Présentation

Les conditions IAM vous permettent de n'accorder l'accès aux ressources de mémoire et de révision de mémoire que si les conditions spécifiées sont remplies. Vous pouvez contrôler l'accès aux souvenirs en fonction du champ scope d'une ressource de mémoire à l'aide de l'attribut d'API "aiplatform.googleapis.com/memoryScope" avec une expression écrite en Common Expression Language. Le champ d'application est un dictionnaire arbitraire fourni lors de la création ou de la génération de souvenirs, comme {'user_id': '123'}, qui vous permet d'organiser les souvenirs en groupes.

Ces stratégies Identity and Access Management conditionnelles sont créées au niveau du projet et s'appliquent à toutes les mémoires d'un projet. Vous pouvez appliquer des conditions IAM à tous les types de comptes principaux, y compris les utilisateurs de votre projet et les comptes de service.

Les conditions IAM sont utiles pour accorder des autorisations Identity and Access Management (IAM) à de nombreuses ressources associées de la banque de données Memory Bank en même temps, y compris à celles qui n'existent pas encore. Vous pouvez limiter l'accès à vos souvenirs et à vos révisions afin qu'un utilisateur ne puisse accéder qu'à ses propres informations, ou afin que les développeurs ne puissent consulter que certaines ressources de la mémoire sans autorisation spéciale.

Avant de commencer

Pour configurer des stratégies IAM conditionnelles pour les souvenirs et les révisions de souvenirs, procédez comme suit :

Consultez les conditions IAM : familiarisez-vous avec la présentation des conditions IAM.
Déterminez les rôles nécessaires : identifiez les rôles IAM spécialisés Memory Bank qui conviennent à votre cas d'utilisation pour respecter le principe du moindre privilège.
Identifier les comptes principaux concernés : identifiez les membres de votre organisation qui doivent recevoir quelles autorisations. Par exemple, prenons le cas suivant :
- Indique si les développeurs doivent pouvoir voir tous les souvenirs.
- Indique si les administrateurs de projet doivent pouvoir voir tous les souvenirs.
- Si certaines identités d'agent ne peuvent accéder qu'à certaines mémoires.
Attribuez des rôles IAM : assurez-vous de disposer des rôles requis contenant les autorisations nécessaires pour effectuer les tâches décrites dans ce document.
Pour obtenir les autorisations nécessaires pour appliquer des conditions IAM aux ressources Vertex AI Agent Engine Memory Bank, demandez à votre administrateur de vous accorder les rôles IAM suivants :
- Pour les projets : Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour appliquer des conditions IAM aux ressources Vertex AI Agent Engine Memory Bank. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises

Les autorisations suivantes sont requises pour appliquer des conditions IAM aux ressources Vertex AI Agent Engine Memory Bank :
- Définissez un accès IAM conditionnel au niveau du projet : resourcemanager.projects.setIamPolicy
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Si vous envisagez d'utiliser des conditions IAM au sein de votre organisation, vous devez également disposer d'autorisations permettant de gérer les règles d'administration.

Créer un accès conditionnel pour les souvenirs

L'accès conditionnel aux mémoires est accordé en ajoutant une condition à une liaison de stratégie IAM au niveau du projet. La condition utilise la fonction api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) pour inspecter le mappage du champ d'application d'une ressource de mémoire. Vous définissez le champ d'application lorsque vous créez ou générez une mémoire.

Pour obtenir un guide détaillé sur la création de stratégies IAM avec des conditions, consultez Conditions dans les stratégies d'autorisation.

Pour attribuer un seul rôle à un compte principal, procédez comme suit :

Console

Dans la console Google Cloud , accédez à la page IAM.

Accéder à IAM
Sélectionnez votre projet.
Sélectionnez un compte principal auquel attribuer un rôle :
- Pour attribuer un rôle à un compte principal qui dispose déjà d'autres rôles sur la ressource, recherchez la ligne contenant le compte principal, puis cliquez sur Modifier le compte principal sur cette ligne, puis sur Ajouter un autre rôle.
  
  Pour attribuer un rôle à un agent de service, cochez la case Inclure les attributions de rôles fournies parGoogle pour afficher son adresse e-mail.
  
  Remarque : Vous ne pouvez pas modifier les rôles hérités lorsque vous gérez l'accès à une ressource. Pour modifier les rôles hérités, accédez à la ressource où le rôle a été accordé.
- Pour attribuer un rôle à un compte principal qui ne dispose d'aucun rôle sur la ressource, cliquez sur Accorder l'accès, puis saisissez un identifiant de compte principal (par exemple, my-user@example.com ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com).
Sélectionnez un rôle à attribuer dans la liste déroulante. Pour respecter les bonnes pratiques de sécurité, choisissez un rôle qui n'inclut que les autorisations dont votre compte principal a besoin. Vous pouvez choisir l'un des rôles IAM spécialisés de la banque de mémoire.
Ajoutez une condition au rôle en utilisant aiplatform.googleapis.com/memoryScope comme attribut d'API. Consultez les exemples ci-dessous pour découvrir des exemples d'énoncés de conditions possibles.
Cliquez sur Enregistrer. Le rôle est attribué au compte principal sur la ressource.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
La commande add-iam-policy-binding vous permet d'attribuer rapidement un rôle à un compte principal.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projets sont alphanumériques, par exemple my-project.
- PRINCIPAL : identifiant du compte principal ou membre, se présentant généralement sous la forme suivante : PRINCIPAL_TYPE:ID. Par exemple, user:my-user@example.com ou principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Pour obtenir la liste complète des valeurs possibles pour PRINCIPAL, consultez Identifiants de comptes principaux.
  
  Pour le type de compte principal user, le nom de domaine indiqué dans l'identifiant doit être un domaine Google Workspace ou Cloud Identity. Pour savoir comment configurer un domaine Cloud Identity, consultez la présentation de Cloud Identity.
- ROLE_NAME : nom du rôle que vous souhaitez révoquer. Utilisez l'un des formats suivants :
  - Rôles prédéfinis : roles/aiplatform.IDENTIFIER
  - Rôles personnalisés au niveau du projet : projects/PROJECT_ID/roles/IDENTIFIER
  Sélectionnez un rôle à attribuer dans la liste déroulante. Pour respecter les bonnes pratiques de sécurité, choisissez un rôle qui n'inclut que les autorisations dont votre compte principal a besoin. Vous pouvez choisir l'un des rôles IAM spécialisés de la banque de mémoire.
- CONDITION : ajoutez une condition au rôle en utilisant aiplatform.googleapis.com/memoryScope comme attribut d'API. Consultez les exemples ci-dessous pour découvrir des exemples d'énoncés de conditions possibles.
Exécutez la commande suivante :
Linux, macOS ou Cloud Shell
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION
```
Windows (PowerShell)
```
gcloud projects add-iam-policy-binding PROJECT_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION
```
Windows (cmd.exe)
```
gcloud projects add-iam-policy-binding PROJECT_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION
```
La réponse contient la stratégie IAM mise à jour.

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base. Pour en savoir plus, lisez la documentation de référence du fournisseur Terraform.

Si vous utilisez Terraform pour définir vos stratégies IAM, vous pouvez inclure une condition dans la ressource google_project_iam_member afin de limiter l'accès d'un membre aux souvenirs.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

Remplacez les variables suivantes :

PROJECT_ID : ID de votre projet Google Cloud . Les ID de projets sont alphanumériques, par exemple my-project.
ROLE : rôle IAM à accorder, par exemple roles/aiplatform.memoryEditor.
MEMBER : compte principal auquel attribuer le rôle, par exemple user:developerA@corp.com. Pour obtenir la liste complète des valeurs possibles pour MEMBER, consultez Identifiants de comptes principaux.
CONDITION : instruction de condition IAM utilisant aiplatform.googleapis.com/memoryScope comme attribut d'API. Consultez les exemples ci-dessous pour découvrir des exemples d'énoncés de conditions possibles.

Bonnes pratiques concernant les autorisations au niveau du champ d'application

Lorsque vous créez des conditions pour la banque de mémoire, suivez les bonnes pratiques suivantes :

Utiliser des rôles Memory Bank spécialisés : les conditions IAM Memory Bank ne doivent être utilisées que pour les rôles qui s'appliquent aux souvenirs et aux révisions de souvenirs. Vous pouvez utiliser des rôles spécialisés tels que aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor et aiplatform.googleapis.com/memoryUser pour éviter les accès trop permissifs. Pour en savoir plus, consultez Rôles IAM Specialized Memory Bank.
Utilisez des conditions positives : nous vous recommandons d'utiliser des conditions positives (telles que des vérifications d'égalité ou la présence de paires clé/valeur) sur aiplatform.googleapis.com/memoryScope pour une plus grande précision. Étant donné que les types et services non compatibles sont représentés par un champ d'application vide, les conditions négatives (telles que les vérifications d'inégalité) peuvent correspondre par inadvertance à un large éventail de ressources, ce qui peut être trop permissif et permettre l'octroi d'autorisations inattendues.
Raccourcissez les conditions si possible : nous vous recommandons d'utiliser la logique la plus courte et la plus simple possible dans vos expressions de conditions IAM, en particulier si vous prévoyez d'avoir un grand nombre de conditions. Les stratégies d'autorisation IAM sont soumises à une limite de taille. Simplifier les conditions permet d'éviter ces limites. Pour en savoir plus, consultez Limites. Par exemple, vous pouvez omettre de vérifier la présence d'une clé dans l'expression 'user_id' in "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA', car elle donne le même résultat que l'instruction plus courte api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Rôles IAM spécialisés pour la banque de mémoire

Il est essentiel d'éviter les stratégies IAM trop permissives lorsque vous utilisez des conditions IAM. Le tableau suivant répertorie les rôles spécialisés que vous pouvez utiliser lorsque vous accordez des rôles IAM conditionnels pour les API Memory Bank :

Nom du rôle	Description	Autorisations associées
`roles/aiplatform.memoryViewer`	Accorde un accès en lecture seule aux souvenirs et à leurs révisions.	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	Accorde un accès en écriture et à la génération pour les mémoires, et un accès à la restauration pour les révisions de mémoire.	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	Accorde un accès complet aux souvenirs et aux révisions, y compris toutes les autorisations de lecteur et d'éditeur.	Inclut toutes les autorisations de `memoryEditor` et de `memoryViewer`.

Utiliser des conditions IAM avec Memory Bank

Cette section présente les exemples suivants d'utilisation des conditions IAM avec Memory Bank :

Accorder un accès en lecture aux souvenirs avec une correspondance exacte du champ d'application.
Accorder l'accès en écriture aux souvenirs avec un champ contenant une paire clé/valeur spécifique.
Accorder un accès complet aux souvenirs avec un champ contenant des clés spécifiques.
Accorder un accès complet aux souvenirs avec un champ d'application contenant un préfixe spécifique.
Accorder un accès complet aux souvenirs avec le champ d'application de la clé et un ensemble de valeurs autorisées.

Accorder un accès en lecture aux souvenirs avec une correspondance exacte du champ d'application

La condition suivante accorde à l'utilisateur userA@gmail.com un accès en lecture uniquement aux souvenirs dont le champ d'application est exactement {"userId": "userA"}.

Cela signifie que le membre peut obtenir et récupérer des souvenirs, ainsi que lister et obtenir les révisions de ces souvenirs, à condition que le champ d'application soit exactement {"userId": "userA"}. L'utilisateur n'a pas accès aux souvenirs avec un champ d'application tel que {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.memoryViewer",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) == {'userId': 'userA'}"
  }
}

Accorder un accès en écriture aux souvenirs avec un champ contenant une paire clé-valeur spécifique

La condition suivante accorde à l'utilisateur developerA@corp.com un accès en modification à tous les souvenirs contenant la paire clé/valeur 'userId': 'userA'.

Cela signifie que l'utilisateur peut créer, modifier, supprimer et générer des souvenirs, ainsi que créer et annuler les révisions de ces souvenirs, avec des niveaux d'accès tels que {'userId': 'userA'} et {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

Accorder un accès complet aux souvenirs avec un champ contenant des clés spécifiques

La condition suivante accorde au groupe d'utilisateurs group:engineering@corp.com (lecteurs et éditeurs) l'accès aux souvenirs qui ont la clé 'admin_override' ou 'public_access_flag'.

Cela signifie que les membres du groupe disposent d'un accès complet en lecture et en écriture aux souvenirs avec des niveaux d'accès tels que {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'} et {'userId': 'userA', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

Accorder un accès complet aux souvenirs avec un champ contenant un préfixe spécifique

La condition suivante accorde au groupe d'utilisateurs group:engineering@corp.com (lecteur et éditeur) l'accès aux souvenirs dont la clé 'userId' a une valeur commençant par 'user'.Vous pouvez utiliser 'startsWith' pour vérifier le préfixe et 'endsWith' pour vérifier le suffixe.

Cela signifie que les membres du groupe ont un accès complet en lecture et en écriture aux souvenirs avec des niveaux d'accès tels que {'userId': 'userA'} et {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

Accorder un accès complet aux souvenirs avec un champ d'application de clé et un ensemble de valeurs autorisées

La condition suivante accorde au groupe d'utilisateurs group:engineering@corp.com (lecteurs et éditeurs) l'accès aux souvenirs qui ont la clé 'userId' avec les valeurs 'userA' ou 'userB'.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] in ['userA', 'userB']"
  }
}

Limites

Limite d'entités principales : les stratégies IAM sont limitées à 1 500 entités principales uniques. Vous pouvez gérer cette limite à l'aide des groupes Google. Pour en savoir plus, consultez Limites sur tous les comptes principaux.
Compatibilité avec l'API ListMemories : l'API ListMemories n'est pas compatible avec les conditions IAM. Pour accorder des autorisations ListMemories, vous devez attribuer au compte principal un rôle inconditionnel, tel que aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryUser ou un rôle Vertex AI inconditionnel pertinent.