Zugriff auf Memory Bank mit IAM Conditions steuern

Mit Memory Bank können Sie den Zugriff auf Erinnerungen und Ressourcen für die Überarbeitung von Erinnerungen basierend auf ihren Bereichsattributen steuern. Mit IAM-Bedingungen können Sie detaillierte Zugriffssteuerungen definieren, z. B. den Zugriff auf bestimmte Nutzer oder Gruppen basierend auf Kriterien, die in der Common Expression Language definiert sind.

In diesem Dokument wird beschrieben, wie Sie Richtlinien für bedingten Zugriff für Erinnerungen und Überarbeitungen in Ihrem Projekt erstellen und anwenden.

Einen Überblick über Berechtigungen finden Sie unter Erforderliche Rollen prüfen.

Übersicht

Mit IAM Conditions können Sie nur dann Zugriff auf Speicher- und Speicherversionsressourcen gewähren, wenn die angegebenen Bedingungen erfüllt sind. Sie können den Zugriff auf Erinnerungen basierend auf dem Feld scope in einer Erinnerungsressource mit dem API-Attribut "aiplatform.googleapis.com/memoryScope" und einem in Common Expression Language geschriebenen Ausdruck steuern. „Scope“ ist ein beliebiges Dictionary, das beim Erstellen oder Generieren von Erinnerungen wie {'user_id': '123'} bereitgestellt wird. Damit können Sie festlegen, welche Erinnerungen zu welcher Gruppe gehören.

Diese bedingten IAM-Richtlinien (Identity and Access Management) werden auf Projektebene erstellt und gelten für alle Erinnerungen in einem Projekt. Sie können IAM-Bedingungen auf alle Arten von Hauptkonten anwenden, einschließlich Nutzer Ihres Projekts und Dienstkonten.

IAM Conditions sind nützlich, um vielen zugehörigen Memory Bank-Ressourcen gleichzeitig IAM-Berechtigungen (Identity and Access Management) zuzuweisen. Dies gilt auch für Ressourcen, die noch nicht vorhanden sind. Sie können den Zugriff auf Ihre Erinnerungen und Überarbeitungen einschränken, sodass ein Nutzer nur auf seine eigenen Informationen zugreifen kann oder Entwickler nur auf bestimmte Memory Bank-Ressourcen zugreifen können, ohne dass spezielle Berechtigungen erforderlich sind.

Hinweis

So richten Sie bedingte IAM-Richtlinien für Erinnerungen und Erinnerungsrevisionen ein:

• IAM Conditions ansehen: Machen Sie sich mit der Übersicht über IAM Conditions vertraut.
• Erforderliche Rollen festlegen: Ermitteln Sie, welche spezialisierten IAM-Rollen für Memory Bank für Ihren Anwendungsfall geeignet sind, um das Prinzip der geringsten Berechtigung zu gewährleisten.

• Betroffene Hauptkonten identifizieren: Legen Sie fest, welche Personen in Ihrer Organisation welche Berechtigungen erhalten sollen. Betrachten Sie beispielsweise Folgendes:

  • Ob Entwickler alle Erinnerungen sehen können.
  • Ob Projektadministratoren alle Erinnerungen sehen können.
  • Ob bestimmte Agent-Identitäten nur auf bestimmte Erinnerungen zugreifen können.
• IAM-Rollen zuweisen: Sie benötigen die erforderlichen Rollen mit den Berechtigungen, die zum Ausführen der Aufgaben in diesem Dokument erforderlich sind.

  Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Anwenden von IAM-Bedingungen auf Agent Platform Memory Bank-Ressourcen benötigen:

  • Für Projekte: Projekt-IAM-Administrator (`roles/resourcemanager.projectIamAdmin`)

  Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

  Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Anwenden von IAM Conditions auf Agent Platform Memory Bank-Ressourcen erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

  Erforderliche Berechtigungen

  Die folgenden Berechtigungen sind erforderlich, um IAM-Bedingungen auf Memory Bank-Ressourcen der Agent Platform anzuwenden:

  • Bedingten IAM-Zugriff auf Projektebene festlegen: `resourcemanager.projects.setIamPolicy`

  Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

  Wenn Sie IAM Conditions in Ihrer gesamten Organisation verwenden möchten, benötigen Sie außerdem Berechtigungen zum Verwalten von Organisationsrichtlinien.

Bedingten Zugriff für Erinnerungen erstellen

Bedingter Zugriff auf Erinnerungen wird gewährt, indem Sie einer IAM-Richtlinienbindung auf Projektebene eine Bedingung hinzufügen. In der Bedingung wird die Funktion api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) verwendet, um die Bereichszuordnung einer Speicherressource zu prüfen. Sie definieren den Umfang, wenn Sie ein Gedächtnis erstellen oder generieren.

Eine detaillierte Anleitung zum Erstellen von IAM-Richtlinien mit Bedingungen finden Sie unter Bedingungen in Zulassungsrichtlinien.

So weisen Sie einem Hauptkonto eine einzelne Rolle zu:

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

Best Practices für Berechtigungen auf Bereichsebene

Beachten Sie beim Erstellen von Bedingungen für Memory Bank die folgenden Best Practices:

1. Spezialisierte Memory Bank-Rollen verwenden: IAM-Bedingungen für Memory Bank sollten nur für Rollen verwendet werden, die für Erinnerungen und Erinnerungsrevisionen gelten. Sie können spezielle Rollen wie aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor und aiplatform.googleapis.com/memoryUser verwenden, um einen zu großzügigen Zugriff zu verhindern. Weitere Informationen finden Sie unter IAM-Rollen für spezialisierte Memory Banks.

2. Positive Bedingungen verwenden: Wir empfehlen, für eine höhere Genauigkeit positive Bedingungen (z. B. Prüfungen auf Gleichheit oder das Vorhandensein von Schlüssel/Wert-Paaren) für aiplatform.googleapis.com/memoryScope zu verwenden. Da nicht unterstützte Typen und Dienste durch einen leeren Bereich dargestellt werden, können negative Bedingungen (z. B. Prüfungen auf Ungleichheit) versehentlich auf eine Vielzahl von Ressourcen zutreffen. Dies kann zu umfassenden Berechtigungen und unerwarteten Berechtigungsvergaben führen.

3. Bedingungen nach Möglichkeit verkürzen: Wir empfehlen, in Ihren IAM-Bedingungsausdrücken die kürzeste und einfachste Logik zu verwenden, insbesondere wenn Sie eine große Anzahl von Bedingungen planen. IAM-Zulassungsrichtlinien haben eine Größenbeschränkung. Durch das Vereinfachen von Bedingungen wird verhindert, dass diese IAM-Beschränkungen erreicht werden. Weitere Informationen finden Sie unter Einschränkungen. Sie können beispielsweise die Prüfung auf das Vorhandensein eines Schlüssels im Ausdruck 'user_id' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' weglassen und stattdessen die kürzere Anweisung api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' verwenden. Wenn der user_id-Schlüssel fehlt, wird der längere Ausdruck zu false ausgewertet, während der kürzere Ausdruck einen Fehler zurückgibt. Da Fehler in IAM-Bedingungsausdrücken dazu führen, dass der Zugriff verweigert wird, führen beide Ausdrücke zum gleichen Ergebnis.

Spezielle IAM-Rollen für Memory Banks

Es ist wichtig, übermäßig permissive IAM-Richtlinien zu verhindern, wenn Sie IAM-Bedingungen verwenden. In der folgenden Tabelle sind spezielle Rollen aufgeführt, die Sie verwenden können, wenn Sie bedingte IAM-Rollen für Memory Bank APIs gewähren:

IAM-Bedingungen mit Memory Bank verwenden

In diesem Abschnitt werden die folgenden Beispiele für die Verwendung von IAM Conditions mit Memory Bank behandelt:

1. Lesezugriff auf Erinnerungen mit genau passendem Bereich gewähren

2. Schreibzugriff auf Erinnerungen mit einem Bereich gewähren, der ein bestimmtes Schlüssel/Wert-Paar enthält

3. Vollständigen Zugriff auf Erinnerungen mit Bereich gewähren, der bestimmte Schlüssel enthält

4. Vollständigen Zugriff auf Erinnerungen mit einem Bereich gewähren, der ein bestimmtes Präfix enthält

5. Vollständigen Zugriff auf Erinnerungen mit dem Bereich des Schlüssels mit einer Reihe zulässiger Werte gewähren.

Lesezugriff auf Erinnerungen mit genauem Bereichsabgleich gewähren

Die folgende Bedingung gewährt dem Nutzer userA@gmail.com nur Lesezugriff auf Erinnerungen mit dem genauen Umfang {"userId": "userA"}.

Das bedeutet, dass das Mitglied Erinnerungen abrufen und abrufen sowie die Überarbeitungen dieser Erinnerungen auflisten und abrufen kann, sofern der Bereich genau {"userId": "userA"} ist. Der Nutzer hat keinen Zugriff auf Erinnerungen mit dem Bereich {'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'}"
  }
}

Schreibzugriff auf Erinnerungen mit einem Bereich gewähren, der ein bestimmtes Schlüssel/Wert-Paar enthält

Die folgende Bedingung gewährt dem einzelnen developerA@corp.com Bearbeitungszugriff auf alle Erinnerungen, die das Schlüssel/Wert-Paar 'userId': 'userA' enthalten.

Das bedeutet, dass der Nutzer mit Bereichen wie {'userId': 'userA'} und {'userId': 'userA', 'source': 'ADK'} Erinnerungen erstellen, aktualisieren, löschen und generieren sowie Versionen dieser Erinnerungen erstellen und zurücksetzen kann.

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

Vollständigen Zugriff auf Erinnerungen mit Bereich gewähren, der bestimmte Schlüssel enthält

Die folgende Bedingung gewährt der Gruppe group:engineering@corp.com Nutzerzugriff (Betrachter und Bearbeiter) auf Erinnerungen mit dem Schlüssel 'admin_override' oder 'public_access_flag'.

Das bedeutet, dass Mitglieder der Gruppe vollen Lese- und Schreibzugriff auf Erinnerungen mit Bereichen wie {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'} und {'userId': 'userA', 'public_access_flag': 'false'} haben.

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

Vollständigen Zugriff auf Erinnerungen mit einem Bereich gewähren, der ein bestimmtes Präfix enthält

Die folgende Bedingung gewährt der Gruppe group:engineering@corp.com Zugriff auf Erinnerungen, die den Schlüssel 'userId' mit einem Wert haben, der mit 'user' beginnt.Sie können 'startsWith' für die Präfixprüfung und 'endsWith' für die Suffixprüfung verwenden.

Das bedeutet, dass Mitglieder der Gruppe vollen Lese- und Schreibzugriff auf Erinnerungen mit Bereichen wie {'userId': 'userA'} und {'userId': 'userB', 'public_access_flag': 'false'} haben.

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

Vollständigen Zugriff auf Erinnerungen mit dem Bereich des Schlüssels und einer Reihe zulässiger Werte gewähren

Die folgende Bedingung gewährt der Gruppe group:engineering@corp.com (Betrachter und Bearbeiter) Zugriff auf Erinnerungen mit dem Schlüssel 'userId' und den Werten 'userA' oder 'userB'.

Das bedeutet, dass Mitglieder der Gruppe vollen Lese- und Schreibzugriff auf Erinnerungen mit Bereichen wie {'userId': 'userA'} und {'userId': 'userB', 'public_access_flag': 'false'} haben.

{
  "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']"
  }
}

Beschränkungen

• Hauptkontenlimit: IAM-Richtlinien sind auf 1.500 eindeutige Hauptkonten beschränkt. Dieses Limit kann mit Google-Gruppen verwaltet werden. Weitere Informationen finden Sie unter Limits für alle Hauptkonten.

• API-Unterstützung: IAM-Bedingungen werden nicht von Methoden unterstützt, die für mehrere Bereiche ausgeführt werden, z. B. ListMemories und PurgeMemories. Um diese Berechtigungen zu gewähren, müssen Sie dem Hauptkonto eine bedingungslose Rolle zuweisen, z. B. aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryUser oder eine entsprechende bedingungslose Rolle für die Gemini Enterprise Agent Platform.