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 Conditions den Zugriff auf Vertex AI Agent Engine-Sitzungsressourcen 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 anhand des Strings userId in der Sitzungsressource mit dem API-Attribut aiplatform.googleapis.com/sessionUserId und einem in Common Expression Language geschriebenen Ausdruck steuern. Die Nutzer-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 Conditions auf alle Arten von Hauptkonten anwenden, einschließlich Nutzern 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 so einschränken, dass ein Nutzer nur auf seine eigenen Informationen zugreifen kann oder Entwickler bestimmte Sitzungsressourcen ohne spezielle Berechtigungen aufrufen können.

Hinweis

So richten Sie bedingte Identity and Access Management-Richtlinien für Sitzungen und Sitzungsereignisse ein:

IAM Conditions prüfen: Machen Sie sich mit der Übersicht zu 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: Ermitteln Sie, welche Personen in Ihrer Organisation welche Berechtigungen erhalten sollen. Beispiel:
- Sollen Nutzer die Sitzungen anderer Nutzer sehen können?
- Sollen Entwickler alle Sitzungen sehen können?
- Sollen Projektadministratoren alle Sitzungen sehen können?
- Sollen bestimmte Agent-Identitäten auf bestimmte Sitzungen zugreifen können?
IAM-Rollen zuweisen: Sie benötigen die erforderlichen Rollen, die die notwendigen Berechtigungen enthalten, um die Aufgaben in diesem Dokument auszuführen.
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Anwenden von IAM Conditions 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, die erforderlich sind:
Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um IAM Conditions 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

Gewähren Sie bedingten Zugriff auf Sitzungen, indem Sie einer IAM-Richtlinienbindung auf Projektebene eine Bedingung hinzufügen. Die Bedingung verwendet die api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") Funktion, um die Nutzer-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 Richtlinien für Zulassungen.

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 Hauptkonto bearbeiten in dieser Zeile und auf Weitere Rolle hinzufügen.
  
  Wenn Sie einem Dienst-Agent eine Rolle zuweisen möchten, wählen Sie das Kästchen Von Google bereitgestellte Rollenzuweisungen einbeziehenGoogleaus, um seine 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 zuweisen 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

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.
Der add-iam-policy-binding Befehl ermöglicht es Ihnen, einem Hauptkonto schnell eine Rolle zuzuweisen.

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, wählen Sie 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 Terraform Anbieter-Referenzdokumentation.

Wenn Sie IAM-Richtlinien mit Terraform festlegen, können Sie der Ressource google_project_iam_member eine Bedingung hinzufü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 zuzuweisende IAM-Rolle, 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 Nutzer-ID-Ebene

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

Spezielle IAM-Rollen für Sitzungen verwenden: IAM Conditions 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 zu umfassenden Zugriff zu verhindern. Weitere Informationen finden Sie im Abschnitt Spezielle IAM-Rollen für Sitzungen.
Positive Bedingungen verwenden: Wir empfehlen, positive Bedingungen (z. B. Prüfungen auf Gleichheit oder das Vorhandensein von Präfixen) für aiplatform.googleapis.com/sessionUserId zu verwenden, um eine höhere Genauigkeit zu erzielen. 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 auf eine Vielzahl von Ressourcen zutreffen, was zu umfassenden Zugriff gewähren und unerwartete Berechtigungen ermöglichen kann.
Bedingungen nach Möglichkeit verkürzen: Wir empfehlen, in Ihren IAM-Bedingungsausdrücken die kürzeste und einfachste Logik zu verwenden, insbesondere wenn Sie viele Bedingungen haben möchten. IAM-Richtlinien für Zulassungen haben eine Größenbeschränkung. Durch das Vereinfachen von Bedingungen können Sie IAM-Beschränkungen vermeiden. Weitere Informationen finden Sie unter Beschrä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 dasselbe Ergebnis wie die kürzere Anweisung api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'] liefert.

Spezielle IAM-Rollen für Sitzungen

Es ist wichtig, zu umfassende 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 Auflistungsereignisse.	`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.	Enthält alle Berechtigungen von `sessionEditor` und `sessionViewer`.

IAM Conditions mit Sitzungen verwenden

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

Lesezugriff auf Sitzungen mit exakter Nutzer-ID-Übereinstimmung gewähren.
Schreibzugriff auf Sitzungen gewähren, die ein bestimmtes Präfix in der Nutzer-ID enthalten.
Vollständigen Zugriff auf Sitzungen gewähren, die eine von zwei Nutzer-IDs enthalten.

Lesezugriff auf Sitzungen mit exakter Nutzer-ID-Übereinstimmung gewähren

Die folgende Bedingung gewährt der Person userA@gmail.com nur Zugriff auf Sitzungen mit der exakten Nutzer-ID userA.

Das bedeutet, dass die Person Sitzungen abrufen und die Sitzungsereignisse auflisten kann, solange die Nutzer-ID genau userA ist. Der Nutzer hat keinen Zugriff auf Sitzungen mit einer anderen Nutzer-ID, z. B. 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 gewähren, die ein bestimmtes Präfix in der Nutzer-ID enthalten

Die folgende Bedingung gewährt der Person developerA@corp.com Bearbeitungszugriff auf alle Sitzungen, deren Nutzer-ID mit user beginnt. Sie können startsWith für die Präfixprüfung und endsWith für die Suffixprüfung verwenden.

Das bedeutet, dass der Entwickler Sitzungen mit Nutzer-IDs wie userA oder user1234 erstellen, aktualisieren und löschen sowie Ereignisse 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 gewähren, die eine von zwei Nutzer-IDs enthalten

Die folgende Bedingung gewährt der Gruppe group:engineering@corp.com Nutzerzugriff (Betrachter und Editor) auf Sitzungen, die nur die Nutzer-IDs userA oder user123 haben.

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

Limit für Hauptkonten: 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.
Unterstützung für die ListSessions-API: Die ListSessions API unterstützt keine IAM Conditions. Wenn Sie Berechtigungen für ListSessions gewähren möchten, müssen Sie dem Hauptkonto eine bedingungslose Rolle zuweisen, z. B. aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser oder eine entsprechende bedingungslose Vertex AI-Rolle.