Zugriffssteuerung für Apps konfigurieren

Auf dieser Seite wird erläutert, wie ein Gemini Enterprise-Administrator die API verwenden kann, um die detaillierte Zugriffssteuerung für einzelne Gemini Enterprise-Apps zu verwalten.

Standardmäßig werden IAM-Berechtigungen häufig auf Projektebene verwaltet. IAM auf App-Ebene ermöglicht eine detailliertere Steuerung, mit der Administratoren Folgendes tun können:

• Den Nutzerzugriff auf bestimmte Apps innerhalb desselben Google Cloud Projekts beschränken
• Berechtigungen an die Anforderungen der Organisation und Datensilos für Ihre Gemini Enterprise-Bereitstellungen anpassen

Wichtig: IAM-Berechtigungen auf Projektebene haben Vorrang vor Richtlinien auf App-Ebene. Wenn einem Nutzer auf Projektebene eine Rolle zugewiesen wird (z. B. roles/discoveryengine.agentspaceUser), kann er auf alle Apps in diesem Projekt zugreifen, unabhängig von Berechtigungen auf App-Ebene. Wenn Sie den Zugriff eines Nutzers auf bestimmte Apps beschränken möchten, müssen Sie die Rolle aus seinen Berechtigungen auf Projektebene entfernen und sie dann auf App-Ebene zuweisen.

Hinweis: Nutzer mit IAM-Berechtigungen auf App-Ebene für eine Gemini Enterprise-App können nur auf diese bestimmte App zugreifen und sie verwenden. Dies sind Berechtigungen auf Nutzerebene, die keine Administratorfunktionen umfassen.

Nehmen wir beispielsweise eine Organisation mit einer HR-App und einer unternehmensweiten App. Ein Mitglied des HR-Teams mit Berechtigungen auf Projektebene kann auf beide Apps zugreifen. Mit einer IAM-Richtlinie auf App-Ebene können Sie einem Mitglied des Vertriebsteams jedoch nur Zugriff auf die unternehmensweite App gewähren und so verhindern, dass es auf die HR-App zugreift.

Hinweis

• Prüfen Sie, ob Sie die Rolle „Gemini Enterprise-Administrator“ haben.

• Prüfen Sie, ob alle Gemini Enterprise-Nutzer mit einer gültigen Lizenz die Gemini Enterprise Restricted User-Rolle haben.

Von Zugriff auf Projektebene zu Zugriff auf App-Ebene wechseln

Wenn Sie den Zugriff von Nutzern auf bestimmte Apps beschränken möchten, müssen Sie die entsprechende Rolle aus den Berechtigungen auf Projektebene entfernen und sie dann auf App-Ebene zuweisen.

Wenn Sie beispielsweise einen Nutzer mit der Rolle „Gemini Enterprise User“ (roles/discoveryengine.agentspaceUser) von der Projektebene auf die App-Ebene verschieben möchten, gehen Sie so vor:

1. Rufen Sie in der Google Cloud Console die Seite IAM auf.
2. Suchen Sie den Nutzer und entfernen Sie die Rolle roles/discoveryengine.agentspaceUser aus seinen Berechtigungen auf Projektebene.
3. Weisen Sie dem Nutzer mit der Methode setIamPolicy die Rolle roles/discoveryengine.agentspaceUser für die bestimmte App zu. Weitere Informationen finden Sie unter IAM-Richtlinien für Apps verwalten.

IAM-Richtlinien für Apps verwalten

Mit den API-Methoden getIamPolicy und setIamPolicy können Sie den Zugriff auf Ihre Gemini Enterprise-App verwalten.

In den folgenden Schritten wird beschrieben, wie Sie die aktuelle Richtlinie abrufen und dann aktualisieren, um den Nutzerzugriff zu gewähren oder zu widerrufen.

IAM-Richtlinie für die App abrufen

Rufen Sie die aktuelle IAM-Richtlinie Ihrer App mit der getIamPolicy Methode ab. Es wird empfohlen, zuerst die vorhandene Richtlinie abzurufen, um zu vermeiden, dass aktuelle Berechtigungen überschrieben werden.

REST

Wichtiger Begriff: In Gemini Enterprise wird der Begriff App im Zusammenhang mit APIs synonym zum Begriff Engine verwendet. Eine Gemini Enterprise-Engine ist eine generische Suchmaschine, bei der das Feld app_type auf APP_TYPE_INTRANET festgelegt ist.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:getIamPolicy"

Ersetzen Sie Folgendes:

• PROJECT_ID: Die Projekt-ID.
• ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:
• us für die Multiregion „USA“
• eu für die Multiregion „EU“
• global für den Standort „Global“

Weitere Informationen zum Festlegen multiregionaler Standorte für Ihren Datenspeicher.

LOCATION: Der multiregionale Standort Ihres Datenspeichers: global, us oder eu.

APP_ID: die ID der App, die Sie erstellen möchten.

Hinweis: Kopieren Sie den Wert etag aus der Antwort. Dieser Wert ist erforderlich, um die IAM-Richtlinie zu aktualisieren. Der Wert etag ändert sich bei jeder Aktualisierung der Richtlinie.

Beispielbefehl und -ergebnis

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:getIamPolicy"

{
  "version": 1,
  "etag": "1234567890"
}
  

IAM-Richtlinie für die App aktualisieren

Wenn Sie den Nutzerzugriff auf die App gewähren oder widerrufen möchten, aktualisieren Sie die IAM Richtlinie der App mit der setIamPolicy Methode.

Wichtig: Die setIamPolicy Methode ersetzt die vorhandene Richtlinie. Damit vorhandene Berechtigungen nicht entfernt werden, muss Ihre Anfrage alle Richtlinienbindungen enthalten, die Sie beibehalten möchten, sowie alle neuen oder geänderten Bindungen.

Die IAM-Richtlinie verwendet die Rolle „Gemini Enterprise User“ (roles/discoveryengine.agentspaceUser), um Nutzern direkten Zugriff auf die App zu gewähren.

Hinweis: Änderungen an IAM-Richtlinien, z. B. mit setIamPolicy, unterliegen einer Weitergabeverzögerung. Es kann einige Minuten dauern, bis die Berechtigungen vollständig weitergegeben wurden. Weitere Informationen finden Sie unter IAM-Weitergabeverzögerung.

REST

Wichtiger Begriff: In Gemini Enterprise wird der Begriff App im Zusammenhang mit APIs synonym zum Begriff Engine verwendet. Eine Gemini Enterprise-Engine ist eine generische Suchmaschine, bei der das Feld app_type auf APP_TYPE_INTRANET festgelegt ist.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "ETAG",
         "bindings": [
          {
            "role": "roles/discoveryengine.agentspaceUser",
            "members": [
              "user:USER_EMAIL",
              "group:GROUP_EMAIL",
              "principal://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ID",
              "principalSet://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/attribute.NAME/VALUE"
            ]
          }
        ]
      }
    }' \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:setIamPolicy"

Ersetzen Sie Folgendes:

• ETAG: Der Wert etag, den Sie als Antwort erhalten haben, als Sie die Methode getIamPolicy verwendet haben.

• USER_EMAIL, GROUP_EMAIL: Eine oder mehrere E-Mail-Adressen von Nutzern oder Gruppen. Neben user und group sind principal und principalSet gültige Mitgliedstypen für die Identitätsföderation von Arbeitslasten.

  • Wenn Sie Zugriff gewähren möchten, fügen Sie Hauptkonten dem Array members hinzu. Beispiel: "user:[e-mail]" oder "group:[e-mail]".

    Hinweis: Vermeiden Sie zusätzliche Leerzeichen vor oder nach der E-Mail-Adresse.

  • Wenn Sie den Zugriff widerrufen möchten, entfernen Sie Hauptkonten aus dem Array members.

• POOL_ID: Die ID Ihres Workload Identity-Pools.

• SUBJECT_ID: Die Subjekt-ID für eine bestimmte Identität.

• NAME: Der Name eines Attributs.

• VALUE: Der Wert eines Attributs.

• PROJECT_ID: Die Projekt-ID.

• ENDPOINT_LOCATION: die Multiregion für Ihre API-Anfrage. Geben Sie einen der folgenden Werte an:

  • us für die Multiregion „USA“
  • eu für die Multiregion „EU“
  • global für den Standort „Global“
  Weitere Informationen finden Sie unter Festlegen multiregionaler Standorte für Ihren Datenspeicher.

• LOCATION: Der multiregionale Standort Ihres Datenspeichers: global, us oder eu.

• APP_ID: die ID der App, die Sie erstellen möchten.

  Hinweis: Der Wert etag ändert sich bei jeder Aktualisierung der Richtlinie. Wenn Sie die Richtlinie noch einmal aktualisieren möchten, müssen Sie zuerst den neuen Wert etag abrufen. Folgen Sie dazu der Anleitung unter IAM-Richtlinie für die App abrufen.

Beispielbefehl und -ergebnis

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "1234567890",
         "bindings": [
          {
            "role": "roles/discoveryengine.user",
            "members": [
              "user:[e-mail]",
              "group:[e-mail]"
            ]
          }
        ]
      }
    }' \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:setIamPolicy"

{
  "version": 1,
  "etag": "2345678901",
  "bindings": [
    {
      "role": "roles/discoveryengine.user",
      "members": [
        "user:cloudysanfrancisco.com",
        "group:[e-mail]"
      ]
    }
  ]
}
  

Nächste Schritte

Wenn Sie eine App mit einer IAM-Richtlinie löschen möchten, können Sie die Nutzer aus der Richtlinie entfernen, bevor Sie die App löschen. Weitere Informationen finden Sie unter Best Practices zum Löschen einer App mit einer IAM-Richtlinie.