Zugriffssteuerung für Datenquellen verwenden

Auf dieser Seite wird beschrieben, wie Sie die Zugriffssteuerung für Datenquellen für Such-Apps in Vertex AI Agent Builder erzwingen.

Mit der Zugriffssteuerung für Ihre Datenquellen in Vertex AI Agent Builder können Sie einschränken, welche Daten Nutzer in den Ergebnissen Ihrer Such-App sehen können. Google verwendet Ihren Identitätsanbieter, um den Endnutzer zu identifizieren, der eine Suche durchführt, und festzustellen, ob er Zugriff auf die Dokumente hat, die als Ergebnisse zurückgegeben werden.

Angenommen, Mitarbeiter in Ihrem Unternehmen suchen mithilfe Ihrer Such-App in Confluence-Dokumenten. Sie müssen jedoch dafür sorgen, dass sie über die App keine Inhalte aufrufen können, auf die sie keinen Zugriff haben. Wenn Sie in Google Cloud einen Mitarbeiterpool für den Identitätsanbieter Ihrer Organisation eingerichtet haben, können Sie diesen Mitarbeiterpool auch in Vertex AI Agent Builder angeben. Wenn ein Mitarbeiter jetzt Ihre App verwendet, erhält er nur Suchergebnisse für Dokumente, auf die sein Konto in Confluence bereits Zugriff hat.

Zugriffssteuerung für Datenquellen

Die Zugriffssteuerung muss nur einmal aktiviert werden.

Die Zugriffssteuerung ist für Cloud Storage, BigQuery, Google Drive und alle Drittanbieterdatenquellen verfügbar.

Wenn Sie die Zugriffssteuerung für Datenquellen für Vertex AI Agent Builder aktivieren möchten, muss der Identitätsanbieter Ihrer Organisation in Google Cloud konfiguriert sein. Die folgenden Authentifizierungsframeworks werden unterstützt:

  • Google-Identität: Wenn Sie die Google-Identität verwenden, sind alle Nutzeridentitäten und ‑gruppen vorhanden und werden über Google Cloud verwaltet. Weitere Informationen zu Google Identity finden Sie in der Google Identity-Dokumentation.

  • Identitätsanbieter-Verknüpfung von Drittanbietern: Wenn Sie einen externen Identitätsanbieter wie Okta oder Azure AD verwenden, müssen Sie die Mitarbeiteridentitätsföderation in Google Cloud einrichten, bevor Sie die Zugriffssteuerung für Datenquellen für Vertex AI Agent Builder aktivieren können.

    Wenn Sie Drittanbieter-Connectors verwenden, muss das Attribut google.subject dem E-Mail-Adressenfeld des externen Identitätsanbieters zugeordnet werden. Im Folgenden finden Sie Beispiele für google.subject- und google.groups-Attributzuordnungen für häufig verwendete Identitätsanbieter:

    • Azure AD mit OIDC-Protokoll 

      google.subject=assertion.email
google.groups=assertion.groups

    • Azure AD mit SAML-Protokoll 

      google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']

    • Okta mit OIDC-Protokoll 

      google.subject=assertion.email
google.groups=assertion.groups

    • Okta mit SAML-Protokoll 

      google.subject=assertion.subject
google.groups=assertion.attributes['groups']

Beschränkungen

Für die Zugriffssteuerung gelten die folgenden Einschränkungen:

  • Pro Dokument sind 250 Leser zulässig. Jedes Hauptkonto wird als Leser gezählt. Ein Hauptkonto kann eine Gruppe oder ein einzelner Nutzer sein.
  • Sie können pro von Vertex AI Search unterstütztem Standort einen Identitätsanbieter auswählen.
  • Die Zugriffssteuerung wird nur für Identitäten und Gruppen berücksichtigt, die in Ihrem Identitätsanbieter explizit definiert sind. Identitäten oder Gruppen, die nativ in Drittanbieter-Apps definiert sind, werden nicht unterstützt.
  • Wenn Sie eine Datenquelle als berechtigt einrichten möchten, müssen Sie diese Einstellung beim Erstellen des Datenspeichers auswählen. Sie können diese Einstellung für einen vorhandenen Datenspeicher nicht aktivieren oder deaktivieren.
  • Auf dem Tab Daten > Dokumente in der Konsole werden keine Daten für datenquellen mit Zugriffssteuerung angezeigt, da diese Daten nur für Nutzer sichtbar sein sollten, die Lesezugriff haben.
  • Wenn Sie eine Vorschau der UI-Ergebnisse für Such-Apps mit Zugriffssteuerung durch Drittanbieter sehen möchten, müssen Sie sich in der föderierten Console anmelden oder die Webanwendung verwenden. Weitere Informationen finden Sie unter Vorschauergebnisse für Apps mit Zugriffssteuerung ansehen.

Hinweise

Bei diesem Verfahren wird davon ausgegangen, dass Sie einen Identitätsanbieter in Ihrem Google Cloud-Projekt eingerichtet haben.

  • Google-Identität: Wenn Sie die Google-Identität verwenden, fahren Sie mit dem Verfahren Mit dem Identitätsanbieter verbinden fort.
  • Drittanbieter-Identitätsanbieter: Sie müssen einen Workforce Identity-Pool für Ihren Drittanbieter-Identitätsanbieter eingerichtet haben. Achten Sie beim Einrichten des Personalpools darauf, Zuordnungen für Subjekt- und Gruppenattribute anzugeben. Informationen zu Attributzuordnungen finden Sie in der IAM-Dokumentation unter Attributzuordnungen. Weitere Informationen zu Workforce Identity-Pools finden Sie in der IAM-Dokumentation unter Workforce Identity-Pool-Anbieter verwalten.

Verbindung mit dem Identitätsanbieter herstellen

So legen Sie einen Identitätsanbieter für Vertex AI Agent Builder fest und aktivieren die Zugriffssteuerung für Datenquellen:

  1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

    Zum Agent Builder

  2. Rufen Sie die Seite Einstellungen > Authentifizierung auf.

  3. Klicken Sie für den Standort, den Sie aktualisieren möchten, auf Identitätsanbieter hinzufügen.

  4. Wählen Sie im Dialogfeld Identitätsanbieter hinzufügen Ihren Identitätsanbieter aus. Wenn Sie einen Identitätsanbieter von Drittanbietern auswählen, wählen Sie auch den Mitarbeiterpool aus, der für Ihre Datenquellen gilt.

  5. Klicken Sie auf Änderungen speichern.

Datenquelle mit Zugriffssteuerung konfigurieren

So wenden Sie die Zugriffssteuerung auf eine Datenquelle an: Gehen Sie je nach Art der Datenquelle so vor:

Unstrukturierte Daten aus Cloud Storage

Wenn Sie einen Datenspeicher für unstrukturierte Daten aus Cloud Storage einrichten, müssen Sie auch ACL-Metadaten hochladen und den Datenspeicher als datenzugriffskontrolliert festlegen:

  1. Fügen Sie bei der Vorbereitung Ihrer Daten ACL-Informationen in Ihre Metadaten ein, indem Sie das Feld acl_info verwenden. Beispiel:

    {
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "content": {
     "mimeType": "<application/pdf or text/html>",
     "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
   },
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

    Weitere Informationen zu unstrukturierten Daten mit Metadaten finden Sie im Abschnitt „Unstrukturierte Daten“ des Artikels Daten für die Aufnahme vorbereiten.

  2. Wenn Sie die Schritte zum Erstellen eines Datenspeichers unter Suchdatenspeicher erstellen ausführen, können Sie die Zugriffssteuerung entweder in der Console oder mithilfe der API aktivieren:

    • Console: Wählen Sie beim Erstellen eines Datenspeichers die Option Dieser Datenspeicher enthält Informationen zur Zugriffssteuerung aus.
    • API: Fügen Sie beim Erstellen des Datenspeichers das Flag "aclEnabled": "true" in die JSON-Nutzlast ein.

  3. Beachten Sie beim Ausführen der Schritte zum Datenimport unter Suchdatenspeicher erstellen Folgendes:

    • Metadaten mit ACL-Informationen aus demselben Bucket wie Ihre unstrukturierten Daten hochladen
    • Wenn Sie die API verwenden, legen Sie GcsSource.dataSchema auf document fest.

Strukturierte Daten aus Cloud Storage

Wenn Sie einen Datenspeicher für strukturierte Daten aus Cloud Storage einrichten, müssen Sie auch ACL-Metadaten hochladen und den Datenspeicher als datenzugriffskontrolliert festlegen:

  1. Fügen Sie bei der Vorbereitung Ihrer Daten ACL-Informationen in Ihre Metadaten ein, indem Sie das Feld acl_info verwenden. Beispiel:

    {
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

  2. Wenn Sie die Schritte zum Erstellen eines Datenspeichers unter Suchdatenspeicher erstellen ausführen, können Sie die Zugriffssteuerung entweder in der Console oder mit der API aktivieren:

    • Console: Wählen Sie beim Erstellen eines Datenspeichers die Option Dieser Datenspeicher enthält Informationen zur Zugriffssteuerung aus.
    • API: Fügen Sie beim Erstellen des Datenspeichers das Flag "aclEnabled": "true" in die JSON-Nutzlast ein.

  3. Beachten Sie beim Ausführen der Schritte zum Datenimport unter Suchdatenspeicher erstellen Folgendes:

    • Metadaten mit ACL-Informationen aus demselben Bucket wie Ihre unstrukturierten Daten hochladen
    • Wenn Sie die API verwenden, legen Sie GcsSource.dataSchema auf document fest.

Unstrukturierte Daten aus BigQuery

Wenn Sie einen Datenspeicher für unstrukturierte Daten aus BigQuery einrichten, müssen Sie den Datenspeicher als datenzugriffskontrolliert festlegen und ACL-Metadaten mit einem vordefinierten Schema für Vertex AI Search angeben:

  1. Geben Sie bei der Vorbereitung Ihrer Daten das folgende Schema an. Verwenden Sie kein benutzerdefiniertes Schema.

    [
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "content",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mimeType",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

  2. Fügen Sie die ACL-Metadaten als Spalte in Ihre BigQuery-Tabelle ein.

  3. Aktivieren Sie bei der Ausführung der Schritte unter Suchdatenspeicher erstellen die Zugriffssteuerung entweder in der Console oder über die API:

    • Console: Wählen Sie beim Erstellen eines Datenspeichers die Option Dieser Datenspeicher enthält Informationen zur Zugriffssteuerung aus.
    • API: Fügen Sie beim Erstellen des Datenspeichers das Flag "aclEnabled": "true" in die JSON-Nutzlast ein.

  4. Wenn Sie die Schritte für den Datenimport unter Suchdatenspeicher erstellen ausführen und die API verwenden, setzen Sie BigQuerySource.dataSchema auf document.

Strukturierte Daten aus BigQuery

Wenn Sie einen Datenspeicher für strukturierte Daten aus BigQuery einrichten, müssen Sie den Datenspeicher als datenzugriffskontrolliert festlegen und ACL-Metadaten mit einem vordefinierten Schema für Vertex AI Search angeben:

  1. Geben Sie bei der Vorbereitung Ihrer Daten das folgende Schema an. Verwenden Sie kein benutzerdefiniertes Schema.

    [
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

  2. Fügen Sie die ACL-Metadaten als Spalte in Ihre BigQuery-Tabelle ein.

  3. Aktivieren Sie bei der Ausführung der Schritte unter Suchdatenspeicher erstellen die Zugriffssteuerung entweder in der Console oder über die API:

    • Console: Wählen Sie beim Erstellen eines Datenspeichers die Option Dieser Datenspeicher enthält Informationen zur Zugriffssteuerung aus.
    • API: Fügen Sie beim Erstellen des Datenspeichers das Flag "aclEnabled": "true" in die JSON-Nutzlast ein.

  4. Beachten Sie beim Ausführen der Schritte für den Datenimport unter Suchdatenspeicher erstellen Folgendes:

    • Wenn Sie die Console verwenden, wählen Sie bei der Angabe der Art der hochgeladenen Daten JSONL für strukturierte Daten mit Metadaten aus.
    • Wenn Sie die API verwenden, legen Sie BigQuerySource.dataSchema auf document fest.

Vorschau der Ergebnisse für Apps mit Zugriffssteuerung für Drittanbieter ansehen

Wenn Sie sich eine Vorschau der Ergebnisse in der Console für Apps mit Zugriffssteuerung durch Drittanbieter ansehen möchten, müssen Sie sich mit den Anmeldedaten Ihrer Organisation anmelden.

Es gibt zwei Möglichkeiten, sich eine Vorschau der UI-Ergebnisse anzusehen:

  • Workforce Identity-Föderationskonsole Öffnen Sie die Console für die Mitarbeiteridentitätsföderation und melden Sie sich mit Ihren Drittanbieter-Anmeldedaten an. Weitere Informationen finden Sie unter Vorschauergebnisse in der Workforce Identity Federation Console.
  • Webanwendung: Aktivieren Sie eine spezielle Webanwendung, die von Vertex AI Search bereitgestellt wird, und melden Sie sich an. Weitere Informationen finden Sie unter Webanwendung aktivieren.

Vorschau der Ergebnisse in der Workforce Identity Federation Console

So rufen Sie die Ergebnisse in der Workforce Identity-Föderationskonsole auf:

  1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

    Zum Agent Builder

  2. Klicken Sie auf den Namen der Such-App, deren Ergebnisse Sie in der Vorschau ansehen möchten.

  3. Rufen Sie die Seite Vorschau auf.

  4. Klicken Sie auf Vorschau mit föderierter Identität, um die Konsole für die Workforce Identity-Föderation aufzurufen.

  5. Geben Sie die Anmeldedaten für den Personalpoolanbieter und die Organisation ein.

  6. Sehen Sie sich auf der Seite Vorschau eine Vorschau der Ergebnisse für Ihre App an.

    Weitere Informationen zur Vorschau Ihrer Suchergebnisse finden Sie unter Suchergebnisse abrufen.

Weitere Informationen zur Workforce Identity Federation Console finden Sie unter Informationen zur Console (föderiert).

Nutzern Suchberechtigungen gewähren

Damit Ihre Nutzer über Ihre App auf datenzugriffskontrollierte Daten zugreifen können, müssen Sie Nutzern in Ihrer Domain oder Ihrem Workforce Pool Zugriff gewähren. Wir empfehlen, Ihrer Nutzergruppe eine benutzerdefinierte IAM-Rolle zuzuweisen.

  • Google Identity: Wenn Sie Google Identity verwenden, empfiehlt Google, eine Google-Gruppe zu erstellen, die alle Mitarbeiter umfasst, die suchen müssen. Wenn Sie Google Workspace-Administrator sind, können Sie alle Nutzer einer Organisation einer Google-Gruppe hinzufügen. Folgen Sie dazu der Anleitung unter Alle Nutzer Ihrer Organisation einer Gruppe hinzufügen.
  • Drittanbieter-Identitätsanbieter: Wenn Sie einen externen Identitätsanbieter wie Okta oder Azure AD verwenden, fügen Sie alle Nutzer in Ihrem Workforce Identity-Pool einer einzigen Gruppe hinzu.

Wir empfehlen, eine benutzerdefinierte IAM-Rolle mit den folgenden Berechtigungen zu erstellen und Ihrer Nutzergruppe zuzuweisen:

  • discoveryengine.answers.get
  • discoveryengine.servingConfigs.answer
  • discoveryengine.servingConfigs.search
  • discoveryengine.sessions.get

Weitere Informationen zu Berechtigungen für Vertex AI Agent Builder-Ressourcen mit Identity and Access Management (IAM) finden Sie unter Zugriffssteuerung mit IAM.

Weitere Informationen zu benutzerdefinierten Rollen finden Sie in der IAM-Dokumentation unter Benutzerdefinierte Rollen.

Such-Widget autorisieren

Wenn Sie ein Such-Widget für eine app mit Zugriffssteuerung bereitstellen möchten, gehen Sie so vor:

  1. Gewähren Sie Nutzern in Ihrer Domain oder Ihrem Mitarbeiterpool, die Such-API aufrufen müssen, die Rolle „Discovery Engine Viewer“.

  2. Generieren Sie Autorisierungstokens, die an Ihr Widget übergeben werden sollen:

  3. Folgen Sie der Anleitung unter Widget mit Autorisierungstoken hinzufügen, um das Token an Ihr Widget zu übergeben.

Webanwendung aktivieren

Die Webanwendung ist eine spezielle Website, die von Vertex AI Search generiert wird. Sie und alle anderen Nutzer mit Anmeldedaten können Ihre Suchanwendung dort verwenden.

Wenn Sie Nutzern die Such-App zur Verfügung stellen möchten, ohne das Such-Widget oder die Such-API in Ihre eigene Anwendung einbinden zu müssen, können Sie Ihren Nutzern die URL der Webanwendung mitteilen.

So aktivieren Sie die Webanwendung:

  1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

    Zum Agent Builder

  2. Klicken Sie auf den Namen der Suchanwendung, für die Sie eine Webanwendung erstellen möchten.

    Die Suchanwendung muss mit mindestens einer Datenquelle mit Zugriffssteuerung verknüpft sein. Weitere Informationen finden Sie unter Datenquelle mit Zugriffssteuerung konfigurieren.

  3. Rufen Sie den Tab Integration > UI auf.

  4. Klicken Sie auf Web-App aktivieren.

  5. Wenn Sie die Workforce Identity-Föderation verwenden, wählen Sie einen Anbieter von Workforce-Pools aus.

  6. Klicken Sie auf den Link zu Ihrer Webanwendung.

  7. Geben Sie die Anmeldedaten für den Personalpoolanbieter und die Organisation ein.

  8. Ergebnisse für Ihre App in der Vorschau ansehen

  9. Informationen zum Konfigurieren der Ergebnisse für die Webanwendung finden Sie unter Ergebnisse für das Such-Widget konfigurieren. Alle Konfigurationen für das Widget gelten auch für die Webanwendung.

  10. Optional: Wenn Sie die Such-App Ihren Nutzern über diese spezielle Webanwendung zur Verfügung stellen möchten, kopieren Sie die URL und senden Sie sie an Nutzer, die Anmeldedaten haben. Sie können die URL der Webanwendung als Lesezeichen speichern und sie aufrufen, um Ihre Suchanwendung zu verwenden.

Weitere Informationen zum Abrufen von Suchergebnissen finden Sie unter Suchergebnisse abrufen.