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

La Memory Bank vous permet de contrôler l'accès aux souvenirs et aux ressources de révision des souvenirs en fonction de leurs attributs de portée. Vous pouvez utiliser les conditions IAM pour définir des contrôles d'accès précis, par exemple en limitant l'accès à des utilisateurs ou des groupes spécifiques en fonction de critères définis dans Common Expression Language.

Ce document explique comment créer et appliquer des règles d'accès conditionnel pour les souvenirs et les révisions de votre projet.

Pour obtenir des informations générales sur les autorisations, consultez Examiner les rôles nécessaires.

Présentation

Les conditions IAM vous permettent d'accorder l'accès aux ressources de mémoire et de révision de mémoire uniquement 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 souvenir à l'aide de l'attribut d'API "aiplatform.googleapis.com/memoryScope" avec une expression écrite en Common Expression Language. "Scope" 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 IAM (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 Memory Bank associées 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 :

• 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 de la banque de données Memory Bank qui conviennent à votre cas d'utilisation pour garantir le principe du moindre privilège.

• Identifiez les comptes principaux concernés : identifiez les membres de votre organisation qui doivent recevoir quelles autorisations. Par exemple, prenons les cas suivants :

  • 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 du Memory Bank de l'Agent Platform, 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 Memory Bank d'Agent Platform. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

  Autorisations requises

  Vous devez disposer des autorisations suivantes pour appliquer des conditions IAM aux ressources Agent Platform 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 de portée d'une ressource 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 :

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"
  }
}

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

Lorsque vous créez des conditions pour Memory Bank, suivez les bonnes pratiques suivantes :

1. Utilisez 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 un accès trop permissif. Pour en savoir plus, consultez les rôles IAM spécialisés pour les banques de mémoire.

2. 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 justesse. É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 inattendu.

3. Raccourcissez les conditions si possible : nous vous recommandons d'utiliser la logique la plus courte et la plus simple dans vos expressions de condition 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. La simplification des conditions permet d'éviter ces limites. Pour en savoir plus, consultez Limites. Par exemple, vous pouvez omettre la vérification de 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' et utiliser l'instruction plus courte api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' à la place. Si la clé user_id est manquante, l'expression la plus longue est évaluée à false, tandis que l'expression la plus courte génère une erreur. Étant donné que les erreurs dans les expressions de condition IAM entraînent le refus de l'accès, les deux expressions produisent le même résultat.

Rôles IAM spécialisés pour les Memory Banks

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

Utiliser des conditions IAM avec Memory Bank

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

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

2. Accorder un accès en écriture aux souvenirs avec un champ d'application contenant une paire clé/valeur spécifique.

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

4. Accorder un accès complet aux souvenirs avec un champ d'application contenant un préfixe spécifique.

5. 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 n'accorde à l'utilisateur userA@gmail.com qu'un accès en lecture 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 dont la portée est {'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 d'application 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, mettre à jour, 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 group:engineering@corp.com un accès utilisateur (lecteur et éditeur) aux souvenirs qui ont la clé 'admin_override' ou 'public_access_flag'.

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 {'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 group:engineering@corp.com l'accès utilisateur (lecteur et éditeur) 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 une portée de clé et un ensemble de valeurs autorisées

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

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'] 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 de groupes Google. Pour en savoir plus, consultez Limites sur tous les comptes principaux.

• Compatibilité avec les API : les conditions IAM ne sont pas compatibles avec les méthodes qui fonctionnent sur plusieurs portées, comme ListMemories et PurgeMemories. Pour accorder ces autorisations, vous devez attribuer au compte principal un rôle inconditionnel, tel que aiplatform.googleapis.com/memoryViewer ou aiplatform.googleapis.com/memoryUser, ou un rôle Gemini Enterprise Agent Platform inconditionnel pertinent.