Zugriff auf Memory Bank mit IAM Conditions steuern

Mit der Memory Bank können Sie den Zugriff auf gemerkte Informationen und Ressourcen zur Überarbeitung gemerkter Informationen anhand ihrer Bereichsattribute steuern. Mit IAM-Bedingungen können Sie detaillierte Zugriffssteuerungen definieren, z. B. den Zugriff auf bestimmte Nutzer oder Gruppen basierend auf Kriterien einschränken, die in der Common Expression Language definiert sind.

In diesem Dokument wird beschrieben, wie Sie Richtlinien für den bedingten Zugriff für gemerkte Informationen und Versionen in Ihrem Projekt erstellen und anwenden.

Eine Übersicht über die Berechtigungen finden Sie unter Erforderliche Rollen prüfen.

Übersicht

Mit IAM-Bedingungen können Sie nur dann Zugriff auf Ressourcen für gemerkte Informationen und Versionen gemerkter Informationen gewähren, wenn die angegebenen Bedingungen erfüllt sind. Sie können den Zugriff auf gemerkte Informationen anhand des Felds scope in einer Ressource für gemerkte Informationen steuern. Verwenden Sie dazu das API-Attribut "aiplatform.googleapis.com/memoryScope" mit einem Ausdruck, der in der Common Expression Language geschrieben ist. Der Bereich ist ein beliebiges Wörterbuch, das beim Erstellen oder Generieren von gemerkten Informationen angegeben wird, z. B. {'user_id': '123'}. Damit können Sie festlegen, welche gemerkten Informationen zu welcher Gruppe gehören.

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

IAM-Bedingungen 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 gemerkten Informationen und Versionen einschränken, sodass ein Nutzer nur auf seine eigenen Informationen zugreifen kann oder Entwickler nur bestimmte Memory Bank-Ressourcen ohne spezielle Berechtigungen sehen können.

Hinweis

So richten Sie bedingte IAM-Richtlinien für gemerkte Informationen und Versionen gemerkter Informationen ein:

  • IAM-Bedingungen prüfen: Machen Sie sich mit der Übersicht über IAM-Bedingungen vertraut.
  • Erforderliche Rollen bestimmen: Ermitteln Sie, welche speziellen Memory Bank-IAM-Rollen für Ihren Anwendungsfall geeignet sind, um das Prinzip der geringsten Berechtigung zu gewährleisten.
  • Betroffene Hauptkonten identifizieren: Ermitteln Sie, wer in Ihrer Organisation welche Berechtigungen erhalten soll. Beispiel:

    • Ob Entwickler alle gemerkten Informationen sehen können sollen.
    • Ob Projektadministratoren alle gemerkten Informationen sehen können sollen.
    • Ob bestimmte Agentenidentitäten nur auf bestimmte gemerkte Informationen zugreifen können.
  • IAM-Rollen zuweisen: Prüfen Sie, ob Sie die erforderlichen Rollen mit den Berechtigungen haben, die Sie zum Ausführen der Aufgaben in diesem Dokument benötigen.

    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-Bedingungen 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 Ressourcen der Agent Platform Memory Bank 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 gemerkte Informationen erstellen

Der bedingte Zugriff auf gemerkte Informationen wird gewährt, indem einer IAM-Richtlinienbindung auf Projektebene eine Bedingung hinzugefügt wird. Die Bedingung verwendet die Funktion api.getAttribute('aiplatform.googleapis.com/memoryScope', {}), um die Bereichszuordnung einer Speicherressource zu prüfen. Sie definieren den Geltungsbereich, wenn Sie eine gemerkte Information erstellen oder generieren.

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

So weisen Sie einem Hauptkonto eine einzelne Rolle zu:

Console

  1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

    IAM aufrufen

  2. Wählen Sie Ihr Projekt aus.

  3. Wählen Sie ein Hauptkonto aus, um in folgenden Fällen eine Rolle zuzuweisen.

    • Wenn Sie einem Hauptkonto eine Rolle zuweisen möchten, das bereits andere Rollen für die Ressource hat, suchen Sie die Zeile mit dem Hauptkonto und klicken Sie in dieser Zeile auf Hauptkonto bearbeiten und auf Weitere Rolle hinzufügen.

      Wenn Sie einem Dienst-Agent eine Rolle zuweisen möchten, müssen Sie das Kästchen Von Googlebereitgestellte Rollenzuweisungen einschließen anklicken, um die entsprechende E-Mail-Adresse zu sehen.

    • Wenn Sie einem Hauptkonto eine Rolle zuweisen möchten, das noch keine Rollen für die Ressource hat, klicken Sie auf Zugriff gewähren und geben Sie dann eine Hauptkonto-ID ein, z. B. my-user@example.com oder //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.

  4. Wählen Sie eine zu gewährende Rolle aus der Drop-down-Liste aus. Wählen Sie als Best Practice für die Sicherheit eine Rolle aus, die nur die Berechtigungen enthält, die das Hauptkonto benötigt. Sie können eine der speziellen IAM-Rollen für Memory Bank auswählen.

  5. Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/memoryScope als API-Attribut. Beispiele für mögliche Bedingungsanweisungen finden Sie in den Beispielen.

  6. Klicken Sie auf Speichern. Dem Hauptkonto wird die Rolle für die Ressource zugewiesen.

gcloud

  1. Aktivieren Sie Cloud Shell in der Google Cloud Console.

    Cloud Shell aktivieren

    Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.

  2. Mit dem Befehl add-iam-policy-binding können Sie einem Hauptkonto schnell eine Rolle zuweisen.

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • PROJECT_ID: Ihre Google Cloud Projekt-ID Projekt-IDs sind alphanumerisch, z. B. my-project.

    • PRINCIPAL: Eine Kennung für das Hauptkonto bzw. Mitglied, die normalerweise die folgende Form hat: PRINCIPAL_TYPE:ID. Beispiel: user:my-user@example.com oder principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Eine vollständige Liste der Werte, die PRINCIPAL haben kann, finden Sie unter Hauptkonto-IDs.

      Beim Hauptkontotyp user muss der Domainname in der Kennung eine Google Workspace- oder Cloud Identity-Domain sein. Informationen zum Einrichten einer Cloud Identity-Domain finden Sie unter Cloud Identity – Übersicht.

    • ROLE_NAME: Der Name der Rolle, die Sie aufheben möchten. Verwenden Sie eines der folgenden Formate:

      • Vordefinierte Rollen: roles/aiplatform.IDENTIFIER
      • Benutzerdefinierte Rollen auf Projektebene: projects/PROJECT_ID/roles/IDENTIFIER

      Wählen Sie eine zu gewährende Rolle aus der Drop-down-Liste aus. Wählen Sie als Best Practice für die Sicherheit eine Rolle aus, die nur die Berechtigungen enthält, die das Hauptkonto benötigt. Sie können eine der speziellen IAM-Rollen für Memory Bank auswählen.

    • CONDITION: Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/memoryScope als API-Attribut. In den Beispielen unten finden Sie einige mögliche Bedingungsanweisungen.

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder 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

    Die Antwort enthält die aktualisierte IAM-Richtlinie:

Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Weitere Informationen finden Sie in der Referenzdokumentation des Anbieters zu Terraform.

Wenn Sie Terraform zum Festlegen Ihrer IAM-Richtlinien verwenden, können Sie in der Ressource google_project_iam_member eine Bedingung einfügen, um den Zugriff eines Mitglieds auf gemerkte Informationen einzuschränken.

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

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID Projekt-IDs sind alphanumerisch, z. B. my-project.
  • ROLE: Die zu gewährende IAM-Rolle, z. B. roles/aiplatform.memoryEditor.
  • MEMBER: Das Hauptkonto, dem die Rolle zugewiesen werden soll, z. B. user:developerA@corp.com. Eine vollständige Liste der Werte, die MEMBER haben kann, finden Sie unter Hauptkonto-IDs.
  • CONDITION: Ihre IAM-Bedingungsanweisung mit aiplatform.googleapis.com/memoryScope als API-Attribut. Beispiele für mögliche Bedingungsanweisungen finden Sie in den Beispielen.

Best Practices für Berechtigungen auf Bereichsebene

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

  1. Spezielle Memory Bank-Rollen verwenden: IAM-Bedingungen für die Memory Bank sollten nur für Rollen verwendet werden, die für gemerkte Informationen und Überarbeitungen von gemerkten Informationen gelten. Sie können spezielle Rollen wie aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor und aiplatform.googleapis.com/memoryUser verwenden, um einen zu weitreichenden Zugriff zu verhindern. Weitere Informationen finden Sie unter Spezielle IAM-Rollen für Memory Bank.

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

  3. Bedingungen nach Möglichkeit kü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 im Abschnitt 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 Schlüssel user_id fehlt, wird der längere Ausdruck zu false ausgewertet, während der kürzere Ausdruck zu einem Fehler führt. Da Fehler in IAM-Bedingungsausdrücken dazu führen, dass der Zugriff verweigert wird, führen beide Ausdrücke zum selben Ergebnis.

Spezielle IAM-Rollen für die Memory Bank

Es ist wichtig, zu freizügige IAM-Richtlinien zu vermeiden, 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 zuweisen:

Rollenname Beschreibung Enthaltene Berechtigungen
roles/aiplatform.memoryViewer Gewährt Lesezugriff auf gemerkte Informationen und deren Überarbeitungen.
  • 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 Gewährt Schreib- und Generierungszugriff auf gemerkte Informationen und Rollback-Zugriff auf Versionen gemerkter Informationen.
  • 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 Gewährt Vollzugriff auf gemerkte Informationen und Versionen, einschließlich aller Betrachter- und Bearbeiterberechtigungen. Umfasst alle Berechtigungen von memoryEditor und memoryViewer.

IAM-Bedingungen mit Memory Bank verwenden

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

  1. Lesezugriff auf Erinnerungen mit genauer Übereinstimmung des Bereichs gewähren.

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

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

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

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

Lesezugriff auf gemerkte Informationen mit genauer Übereinstimmung des Bereichs gewähren

Mit der folgenden Bedingung wird der Person userA@gmail.com nur Lesezugriff auf gemerkte Informationen gewährt, die genau den Bereich {"userId": "userA"} haben.

Das bedeutet, dass das Mitglied gemerkte Informationen abrufen und auflisten sowie die Überarbeitungen dieser gemerkten Informationen abrufen kann, solange der Bereich genau {"userId": "userA"} ist. Der Nutzer hat keinen Zugriff auf gemerkte Informationen mit einem Bereich wie {'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 gemerkte Informationen mit einem Bereich gewähren, der ein bestimmtes Schlüssel/Wert-Paar enthält

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

Das bedeutet, dass der Nutzer die Möglichkeit hat, Memorys zu erstellen, zu aktualisieren, zu löschen und zu generieren sowie Versionen dieser Memorys zu erstellen und zurückzusetzen, mit Bereichen wie {'userId': 'userA'} und {'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'"
  }
}

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

Mit der folgenden Bedingung wird der Gruppe group:engineering@corp.com Nutzerzugriff (Betrachter und Bearbeiter) auf gemerkte Informationen gewährt, die den Schlüssel 'admin_override' oder 'public_access_flag' haben.

Das bedeutet, dass Mitglieder der Gruppe vollen Lese- und Schreibzugriff auf gemerkte Informationen 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 gemerkte Informationen mit einem Bereich gewähren, der ein bestimmtes Präfix enthält

Die folgende Bedingung gewährt der Gruppe group:engineering@corp.com Nutzerzugriff (Betrachter und Bearbeiter) auf Memories, 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 Speicher mit Bereichen wie {'userId': 'userA'}, {'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 gemerkte Informationen mit Schlüsselbereich mit einer Reihe zulässiger Werte gewähren

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

Das bedeutet, dass Mitglieder der Gruppe vollen Lese- und Schreibzugriff auf Memorys mit Bereichen wie {'userId': 'userA'}, {'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

  • Hauptkontolimit: IAM-Richtlinien sind auf 1.500 eindeutige Hauptkonten beschränkt. Dieses Limit kann mithilfe von Google Groups 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 gelten, z. B. ListMemories und PurgeMemories. Wenn Sie diese Berechtigungen gewähren möchten, müssen Sie dem Hauptkonto eine bedingungslose Rolle zuweisen, z. B. aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryUser oder eine relevante bedingungslose Gemini Enterprise Agent Platform-Rolle.