Zugriff auf Memory Bank mit IAM Conditions steuern

Standardmäßig gelten die Berechtigungen für Identity and Access Management für den Arbeitsspeicher auf Projektebene. In diesem Dokument wird beschrieben, wie Sie mit IAM Conditions den Zugriff auf Vertex AI Agent Engine Memory Bank-Ressourcen detaillierter steuern.

Übersicht

Mit IAM Conditions können Sie nur dann Zugriff auf Ressourcen für Arbeitsspeicher und Arbeitsspeicherrevisionen 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 organisieren, welche Erinnerungen zu welcher Gruppe gehören.

Diese bedingten Identity and Access Management-Richtlinien 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.

Hinweise

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 ermitteln: Ermitteln Sie, welche speziellen IAM-Rollen für Memory Bank für Ihren Anwendungsfall geeignet sind, um das Prinzip der geringsten Berechtigung zu gewährleisten.
Betroffene Hauptkonten ermitteln: Legen Sie fest, wer in Ihrer Organisation welche Berechtigungen erhalten soll. Betrachten Sie beispielsweise Folgendes:
- Gibt an, ob Entwickler alle Erinnerungen sehen können.
- Ob Projektadministratoren alle Erinnerungen sehen können.
- Ob bestimmte Agentenidentitä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 Vertex AI Agent Engine 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 Vertex AI Agent Engine 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 Conditions auf Memory Bank-Ressourcen von Vertex AI Agent Engine 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 einer IAM-Richtlinienbindung auf Projektebene eine Bedingung hinzugefügt wird. In der Bedingung wird die api.getAttribute('aiplatform.googleapis.com/memoryScope', {})-Funktion verwendet, um die Bereichszuordnung einer Speicherressource zu prüfen. Sie definieren den Umfang, wenn Sie einen Kontext 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:

Console

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

IAM aufrufen
Wählen Sie Ihr Projekt aus.
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 VonGooglebereitgestellte Rollenzuweisungen einschließen anklicken, um die entsprechende E-Mail-Adresse zu sehen.
  
  Hinweis: Übernommene Rollen können beim Bearbeiten des Zugriffs auf eine Ressource nicht bearbeitet werden. Zur Bearbeitung übernommener Rollen rufen Sie die Ressource auf, der die Rolle zugewiesen wurde.
- 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.
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.
Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/memoryScope als API-Attribut. Unten finden Sie einige Beispiele für mögliche Bedingungsanweisungen.
Klicken Sie auf Speichern. Dem Hauptkonto wird die Rolle für die Ressource zugewiesen.

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.
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 für PRINCIPAL zulässigen Werte 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. Unten finden Sie einige Beispiele für 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 eine Bedingung in die Ressource google_project_iam_member einfügen, um den Zugriff eines Mitglieds auf Erinnerungen 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 IAM-Rolle, die zugewiesen werden soll, 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 für MEMBER zulässigen Werte finden Sie unter Hauptkonto-IDs.
CONDITION: Ihre IAM-Bedingungsanweisung mit aiplatform.googleapis.com/memoryScope als API-Attribut. Unten finden Sie einige Beispiele für mögliche Bedingungsanweisungen.

Best Practices für Berechtigungen auf Bereichsebene

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

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 Spezialisierte IAM-Rollen für Memory Bank.
Positive Bedingungen verwenden: Wir empfehlen, für aiplatform.googleapis.com/memoryScope positive Bedingungen zu verwenden, z. B. Prüfungen auf Gleichheit oder das Vorhandensein von Schlüssel/Wert-Paaren, 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 umfassenden Berechtigungen führen und unerwartete Berechtigungen ermöglichen.
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, da er zum selben Ergebnis führt wie die kürzere Anweisung api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Spezialisierte IAM-Rollen für Memory Bank

Es ist wichtig, zu großzügige IAM-Richtlinien zu verhindern, wenn Sie IAM Conditions 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:

Rollenname	Beschreibung	Enthaltene Berechtigungen
`roles/aiplatform.memoryViewer`	Gewährt Lesezugriff auf Erinnerungen und Erinnerungsrevisionen.	`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 Erinnerungen und Rollback-Zugriff auf Erinnerungsrevisionen.	`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 vollständigen Zugriff auf Erinnerungen und Überarbeitungen, 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 Conditions mit Memory Bank behandelt:

Lesezugriff auf Erinnerungen mit genau passendem Umfang gewähren
Schreibzugriff auf Erinnerungen mit einem Bereich gewähren, der ein bestimmtes Schlüssel/Wert-Paar enthält:
Vollständigen Zugriff auf Erinnerungen mit Bereich gewähren, der bestimmte Schlüssel enthält
Vollständigen Zugriff auf Erinnerungen mit einem Bereich gewähren, der ein bestimmtes Präfix enthält:
Vollständigen Zugriff auf Erinnerungen mit dem Bereich des Schlüssels mit einer Reihe zulässiger Werte gewähren.

Lesezugriff auf Erinnerungen mit genau passendem Bereich gewähren

Die folgende Bedingung gewährt dem einzelnen userA@gmail.com-Nutzer nur Zugriff 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 Bereichen 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 Erinnerungen mit einem Umfang gewähren, der ein bestimmtes Schlüssel/Wert-Paar enthält

Die folgende Bedingung gewährt dem Nutzer 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 (Betrachter und Bearbeiter) Zugriff 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

Mit der folgenden Bedingung wird Nutzern (Betrachtern und Bearbeitern) der Gruppe group:engineering@corp.com Zugriff auf Erinnerungen gewährt, 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')"
  }
}

Vollzugriff 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 Nutzerzugriff (Betrachter und Editor) auf Erinnerungen mit dem Schlüssel 'userId' und den Werten 'userA' oder 'userB'.