Zugriff auf Sitzungen mit IAM Conditions steuern

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

Übersicht

Mit IAM Conditions können Sie nur dann Zugriff auf Sitzungs- und Sitzungsereignisressourcen gewähren, wenn die angegebenen Bedingungen erfüllt sind. Sie können den Zugriff auf Sitzungen basierend auf dem String userId in der Sitzungsressource mit dem API-Attribut aiplatform.googleapis.com/sessionUserId und einem in Common Expression Language geschriebenen Ausdruck steuern. Die User-ID ist ein beliebiger String, der beim Erstellen von Sitzungen angegeben wird, z. B. userId = "userA".

Diese bedingten Identity and Access Management-Richtlinien werden auf Projektebene erstellt und gelten für alle Sitzungen und Sitzungsereignisse 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 Sitzungsressourcen 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 Sitzungen und Ereignisse einschränken, sodass ein Nutzer nur auf seine eigenen Informationen zugreifen kann oder Entwickler nur bestimmte Sitzungsressourcen ohne besondere Berechtigungen aufrufen können.

Hinweise

So richten Sie bedingte IAM-Richtlinien (Identity and Access Management) für Sitzungen und Sitzungsereignisse 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 Sitzungen 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:
- Sollen Nutzer die Sitzungen anderer Nutzer sehen können?
- Sollten Entwickler alle Sitzungen sehen können?
- Sollten Projektadministratoren alle Sitzungen sehen können?
- Sollen bestimmte Kundenservicemitarbeiter auf bestimmte Sitzungen 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-Sitzungsressourcen 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-Sitzungsressourcen erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um IAM-Bedingungen auf Vertex AI Agent Engine-Sitzungsressourcen 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 Sitzungen erstellen

Sie können bedingten Zugriff auf Sitzungen gewähren, indem Sie einer IAM-Richtlinienbindung auf Projektebene eine Bedingung hinzufügen. In der Bedingung wird die api.getAttribute('aiplatform.googleapis.com/sessionUserId', "")-Funktion verwendet, um die User-ID der Sitzungsressource zu prüfen. Sie definieren eine Nutzer-ID, wenn Sie eine Sitzung erstellen.

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 Sitzungen auswählen.
Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/sessionUserId 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 Sitzungen auswählen.
- CONDITION: Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/sessionUserId 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 google_project_iam_member-Ressource einfügen, um den Zugriff eines Mitglieds auf Sitzungen einzuschränken.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Session Access Condition"
    description = "IAM condition for Session"
    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.sessionEditor.
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/sessionUserId als API-Attribut. Unten finden Sie einige Beispiele für mögliche Bedingungsanweisungen.

Best Practices für Berechtigungen auf User-ID-Ebene

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

Spezielle IAM-Rollen für Sitzungen verwenden: IAM-Bedingungen für Sitzungen sollten nur für Rollen verwendet werden, die für Sitzungen und Sitzungsereignisse gelten. Sie können spezielle Rollen wie aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor und aiplatform.googleapis.com/sessionUser verwenden, um einen zu großzügigen Zugriff zu verhindern. Weitere Informationen finden Sie im Abschnitt Spezialisierte IAM-Rollen für Sitzungen.
Positive Bedingungen verwenden: Wir empfehlen, für aiplatform.googleapis.com/sessionUserId positive Bedingungen zu verwenden, z. B. Prüfungen auf Gleichheit oder das Vorhandensein von Präfixen, um die Genauigkeit zu erhöhen. Da nicht unterstützte Typen und Dienste durch eine leere Nutzer-ID 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 lassen sich IAM-Beschränkungen vermeiden. Weitere Informationen finden Sie unter Einschränkungen. Sie können beispielsweise die Prüfung auf zwei verschiedene Nutzer-IDs vereinfachen, indem Sie die zusammengesetzte Anweisung api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB' verwenden, da sie zum gleichen Ergebnis führt wie die kürzere Anweisung api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Spezialisierte IAM-Rollen für Sitzungen

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 Sitzungs-APIs zuweisen:

Rollenname	Beschreibung	Enthaltene Berechtigungen
`roles/aiplatform.sessionViewer`	Gewährt Lesezugriff auf Sitzungen und Listeneinträge.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Gewährt Schreibzugriff auf Sitzungen und das Anhängen von Ereignissen.	`aiplatform.googleapis.com/sessions.create` `aiplatform.googleapis.com/sessions.update` `aiplatform.googleapis.com/sessions.delete` `aiplatform.googleapis.com/sessionEvents.append`
`roles/aiplatform.sessionUser`	Gewährt vollständigen Zugriff auf Sitzungen und Ereignisse, einschließlich aller Berechtigungen für Betrachter und Editoren.	Umfasst alle Berechtigungen von `sessionEditor` und `sessionViewer`.

IAM-Bedingungen mit Sitzungen verwenden

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

Lesezugriff auf Sitzungen mit genau übereinstimmender Nutzer-ID gewähren:
Schreibzugriff auf Sitzungen mit einem bestimmten Präfix in der Nutzer-ID gewähren
Vollständigen Zugriff auf Sitzungen mit einer von zwei User-IDs gewähren

Lesezugriff auf Sitzungen mit genau übereinstimmender User-ID gewähren

Mit der folgenden Bedingung wird der Zugriff auf die Datenansicht userA@gmail.com nur für Sitzungen mit der User-ID userA gewährt.

Das bedeutet, dass die Person Sitzungen abrufen und die Sitzungsereignisse auflisten kann, sofern die Nutzer-ID genau userA ist. Der Nutzer hat keinen Zugriff auf Sitzungen mit einer User-ID wie userB.

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

Schreibzugriff auf Sitzungen mit einem bestimmten Präfix in der Nutzer-ID gewähren

Mit der folgenden Bedingung erhält die Person developerA@corp.com Bearbeitungszugriff auf alle Sitzungen, die die User-ID mit dem Präfix user enthalten. Mit startsWith können Sie Präfixe und mit endsWith Suffixe prüfen.

Das bedeutet, dass der Entwickler Sitzungen erstellen, aktualisieren und löschen sowie Ereignisse mit Nutzer-IDs wie userA oder user1234 anhängen kann.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

Vollständigen Zugriff auf Sitzungen mit einer von zwei Nutzer-IDs gewähren

Mit der folgenden Bedingung erhält die Gruppe group:engineering@corp.com (Betrachter und Bearbeiter) Zugriff auf Sitzungen mit den Nutzer-IDs userA oder user123.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

Beschränkungen

Hauptkontolimit: IAM-Richtlinien sind auf 1.500 eindeutige Hauptkonten beschränkt. Dieses Limit kann mit Google Groups verwaltet werden. Weitere Informationen finden Sie unter Limits für alle Hauptkonten.
ListSessions API-Unterstützung: Die ListSessions API unterstützt keine IAM-Bedingungen. Wenn Sie Berechtigungen für ListSessions gewähren möchten, müssen Sie dem Prinzipal eine bedingungslose Rolle wie aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser oder eine entsprechende bedingungslose Vertex AI-Rolle zuweisen.