Zugriff auf Sitzungen mit IAM Conditions steuern

Standardmäßig gelten die IAM-Berechtigungen (Identity and Access Management) für Sitzungen auf Projektebene. In diesem Dokument wird beschrieben, wie Sie mit IAM-Bedingungen den Zugriff auf Agent Platform-Sitzungsressourcen detaillierter steuern können.

Übersicht

Mit IAM-Bedingungen 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 steuern. Verwenden Sie dazu das API-Attribut aiplatform.googleapis.com/sessionUserId mit einem Ausdruck, der in der Common Expression Language geschrieben ist. 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 innerhalb eines Projekts. 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 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 spezielle Berechtigungen aufrufen können.

Hinweis

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

  • IAM-Bedingungen prüfen: Machen Sie sich mit der Übersicht über IAM-Bedingungen vertraut.
  • Erforderliche Rollen bestimmen: 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 identifizieren: Ermitteln Sie, wer in Ihrer Organisation welche Berechtigungen erhalten soll. Sie könnten beispielsweise Folgendes versuchen:
    • Sollten Nutzer die Sitzungen anderer Nutzer sehen können?
    • Sollen Entwickler alle Sitzungen sehen können?
    • Sollen Projektadministratoren alle Sitzungen sehen können?
    • Sollen bestimmte KI-Agenten-Identitäten auf bestimmte Sitzungen 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 Sessions-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 Sessions-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 Agent Platform-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-Bedingungen 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 Identity and Access Management-Richtlinienbindung auf Projektebene eine Bedingung hinzufügen. Die Bedingung verwendet die Funktion api.getAttribute('aiplatform.googleapis.com/sessionUserId', ""), um die Nutzer-ID der Sitzungsressource zu prüfen. Sie definieren eine Nutzer-ID, wenn Sie eine Sitzung erstellen.

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. Beispiel: 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 Sitzungen auswählen.

  5. Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/sessionUserId als API-Attribut. In den folgenden Beispielen finden Sie einige mögliche Bedingungsanweisungen.

  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 Sitzungen auswählen.

    • CONDITION: Fügen Sie der Rolle eine Bedingung hinzu und verwenden Sie aiplatform.googleapis.com/sessionUserId 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 eine Bedingung in die Ressource google_project_iam_member 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 zu gewährende 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 Werte, die MEMBER haben kann, finden Sie unter Hauptkonto-IDs.
  • CONDITION: Ihre IAM-Bedingungsanweisung mit aiplatform.googleapis.com/sessionUserId als API-Attribut. In den Beispielen unten finden Sie einige 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:

  1. 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 weitreichenden Zugriff zu verhindern. Weitere Informationen finden Sie im Abschnitt Spezielle IAM-Rollen für Sitzungen.

  2. 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 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 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 werden IAM-Einschränkungen vermieden. Weitere Informationen finden Sie im Abschnitt 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' kombinieren, 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 freizügige IAM-Richtlinien zu vermeiden, wenn Sie IAM-Bedingungen verwenden. In der folgenden Tabelle sind spezielle Rollen aufgeführt, die Sie beim Zuweisen bedingter IAM-Rollen für Sitzungs-APIs verwenden können:

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 Betrachter- und Bearbeiterberechtigungen. 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-Bedingungen mit Sitzungen behandelt:

  1. Lesezugriff auf Sitzungen mit genauer Übereinstimmung der Nutzer-ID gewähren.

  2. Schreibzugriff auf Sitzungen gewähren, die ein bestimmtes Präfix in der Nutzer-ID enthalten.

  3. Vollständigen Zugriff auf Sitzungen gewähren, die eine von zwei Nutzer-IDs enthalten.

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

Mit der folgenden Bedingung wird der Person userA@gmail.com nur Lesezugriff auf Sitzungen mit der genauen Nutzer-ID userA gewährt.

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 der Nutzer-ID 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 wird der Person developerA@corp.com Bearbeitungszugriff auf alle Sitzungen gewährt, die die Nutzer-ID enthalten, die 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 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 gewähren, die eine von zwei Nutzer-IDs enthalten

Die folgende Bedingung gewährt der Gruppe group:engineering@corp.com Nutzerzugriff (Betrachter und Bearbeiter) 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

  1. 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.

  2. ListSessions API-Unterstützung: Die ListSessions API unterstützt keine IAM-Bedingungen. Wenn Sie die Berechtigung „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 relevante bedingungslose Gemini Enterprise Agent Platform-Rolle.