Zugriff auf Sitzungen mit IAM Conditions steuern

Standardmäßig gelten IAM-Berechtigungen (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 genauer steuern können.

Ü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 userId-String 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-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.

Hinweis

So richten Sie bedingte Identity and Access Management-Richtlinien 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 identifizieren: Legen Sie fest, welche Personen in Ihrer Organisation welche Berechtigungen erhalten sollen. Betrachten Sie beispielsweise die folgenden Szenarien:
  • Sollten Nutzer die Sitzungen anderer Nutzer sehen können?
  • Sollten Entwickler alle Sitzungen sehen können?
  • Sollten Projektadministratoren alle Sitzungen sehen können?
  • Sollen bestimmte Identitäten von KI-Agenten 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 Funktion api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") 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:

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

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 großzügigen Zugriff zu verhindern. Weitere Informationen finden Sie im Abschnitt IAM-Rollen für spezielle Sitzungen.

2. Positive Bedingungen verwenden: Wir empfehlen, für eine höhere Genauigkeit positive Bedingungen (z. B. Prüfungen auf Gleichheit oder das Vorhandensein von Präfixen) für aiplatform.googleapis.com/sessionUserId zu verwenden. 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. Dies kann zu umfassenden Berechtigungen und unerwarteten Berechtigungsvergaben führen.

3. 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 werden IAM-Beschränkungen vermieden. 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 selben 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, übermäßig permissive IAM-Richtlinien zu verhindern, 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:

IAM-Bedingungen mit Sitzungen verwenden

Dieser Abschnitt enthält die folgenden Beispiele für die Verwendung von IAM Conditions mit Sitzungen:

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

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

3. Vollständigen Zugriff auf Sitzungen mit einer von zwei User-IDs gewähren

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

Mit der folgenden Bedingung erhält der Nutzer userA@gmail.com nur Lesezugriff auf Sitzungen mit der Nutzer-ID userA.

Das bedeutet, dass die Person Sitzungen abrufen und die Sitzungsereignisse auflisten kann, sofern die Nutzer-ID genau userA lautet. Der Nutzer hat keinen Zugriff auf Sitzungen mit der User-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 erhält die Person developerA@corp.com Bearbeitungszugriff auf alle Sitzungen, die die User-ID mit dem Präfix user enthalten. 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 mit einer von zwei User-IDs gewähren

Mit der folgenden Bedingung erhält die Gruppe group:engineering@corp.com (Betrachter und Bearbeiter) Zugriff 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. Hauptkontenlimit: 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.

2. ListSessions-API-Unterstützung: Die ListSessions API unterstützt keine IAM-Bedingungen. Um die Berechtigungen für ListSessions zu gewähren, müssen Sie dem Prinzipal eine bedingungslose Rolle wie aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser oder eine entsprechende bedingungslose Rolle für die Gemini Enterprise Agent Platform zuweisen.