Veröffentlichungszugriff steuern

Identity and Access Management (IAM) bietet verschiedene Richtlinientypen, mit denen Sie steuern können, auf welche Ressourcen Principals zugreifen können. In diesem Leitfaden wird beschrieben, wie Sie Zugriffsrichtlinien verwenden, um den Zugriff beim Veröffentlichen von Ereignisnachrichten in einem Eventarc Advanced-Bus zu steuern.

IAM-Zugriffsrichtlinien können den Zugriff auf Ressourcen sowohl zulassen als auch verweigern. Im Gegensatz zu IAM-Zulassungs- und ‑Ablehnungsrichtlinien kann mit Zugriffsrichtlinien jedoch der Zugriff basierend auf bestimmten Attributen des Ereigniskontexts gewährt oder verweigert werden, z. B. der Priorität der Ereignismeldung.

Jede Zugriffsrichtlinie besteht aus einer Reihe von Regeln, mit denen Sie Hauptkonten identifizieren und Bedingungen definieren können, die die Anwendbarkeit einer Regel bestimmen. So können Sie eine detaillierte Zugriffssteuerung aktivieren. Je nach Auswertung eines CEL-Ausdrucks (Common Expression Language), der auf ein Attribut des Ereigniskontexts angewendet wird, können Sie beispielsweise die Berechtigung zum Veröffentlichen einer Teilmenge von Ereignisnachrichten in einem Eventarc Advanced-Bus zulassen oder verweigern.

In dieser Anleitung wird beschrieben, wie Sie eine Zugriffsrichtlinie erstellen und anwenden. Dazu erstellen Sie zuerst eine Zugriffsrichtlinie und dann eine Richtlinienbindung, um diese Richtlinie mit einem Google Cloud Projekt zu verknüpfen.

Hinweise

Bevor Sie eine Zugriffsrichtlinie erstellen und anwenden, sollten Sie bereits einen Eventarc Advanced-Bus erstellt haben, in dem Ereignisnachrichten veröffentlicht werden können.

  1. Beachten Sie Folgendes:

    • Zugriffsrichtlinien müssen auf ein Google Cloud Projekt angewendet oder daran gebunden werden. Jede Zugriffsrichtlinie kann an bis zu 5 Projekte angehängt werden. An jedes Projekt können bis zu 5 Zugriffsrichtlinien angehängt werden. Sie können einen Bus proGoogle Cloud -Projekt und unterstützter Region erstellen. Eine Zugriffsrichtlinie, die an ein Projekt angehängt ist, steuert den Veröffentlichungszugriff auf alle Eventarc Advanced-Busse in diesem Projekt.

    • Sie können Zugriff auf die Veröffentlichung in einem Eventarc Advanced-Bus mit Zugriffsrichtlinien steuern, aber nicht den Zugriff auf das Abonnieren von Nachrichten aus einem bestimmten Bus. Die unterstützte Berechtigung ist eventarc.messageBuses.publish.

    • Die Zugriffssteuerung kann nur auf Attributen des Ereigniskontexts und nicht auf dem Inhalt der Ereignisnutzlast basieren.

    • Ereignisnachrichten, die aus Google-Quellen veröffentlicht werden und abgelehnt werden, werden verworfen. Wenn der Prinzipal eine Ereignismeldung direkt veröffentlicht, wird dies durch eine Event published successfully-Protokollmeldung angegeben. Wenn die Ereignismeldung jedoch von der Bedingung in der Zugriffsrichtlinie abgelehnt wird, tritt ein Fehler ähnlich dem folgenden auf:

      ERROR: (gcloud.beta.eventarc.message-buses.publish)
PERMISSION_DENIED: Permission 'eventarc.googleapis.com/messageBuses.publish' denied on resource due to an IAM Access Policy.
This command is authenticated as user@example.com which is the active account specified by the [core/account] property.
'@type': type.googleapis.com/google.rpc.ErrorInfo
domain: iam.googleapis.com
metadata:
permission: eventarc.googleapis.com/messageBuses.publish
reason: IAM_PERMISSION_DENIED

  2. Aktivieren Sie die Eventarc API und die IAM API, falls noch nicht geschehen:

    gcloud services enable eventarc.googleapis.com \
    eventarcpublishing.googleapis.com \
    iam.googleapis.com

  3. Richten Sie die Authentifizierung ein:

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST API

    Wenn Sie die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, verwenden Sie die Anmeldedaten, die Sie der gcloud CLI bereitstellen.

      Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    Weitere Informationen finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter Für die Verwendung von REST authentifizieren.

    Erforderliche Rollen

    Eine IAM-Rolle enthält eine Reihe von Berechtigungen, mit denen Sie bestimmte Aktionen für Google Cloud -Ressourcen ausführen können.

    Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen für diese Aufgabe haben:

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Steuern des Veröffentlichungszugriffs erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

    Erforderliche Berechtigungen

    Die folgenden Berechtigungen sind erforderlich, um den Veröffentlichungszugriff zu steuern:

    • Zugriffsrichtlinien erstellen: iam.accessPolicies.create
    • Zugriffsrichtlinien anwenden:
      • iam.accessPolicies.bind
      • resourcemanager.projects.createPolicyBinding

    Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

    Zugriffsrichtlinie erstellen

    Erstellen Sie eine Zugriffsrichtlinie, um den Zugriff beim Veröffentlichen in einem Eventarc Advanced-Bus in Ihrem Projekt zu steuern.

    Sie können eine Zugriffsrichtlinie mit der Google Cloud CLI oder durch Senden einer direkten Anfrage an die IAM v3 API erstellen.

    gcloud

    Sie können eine Zugriffsrichtlinie erstellen, indem Sie den Befehl gcloud beta iam access-policies create ausführen.

    gcloud beta iam access-policies create POLICY_ID \
    --project=POLICY_PROJECT_ID \
    --location=global \
    --details-rules=description="POLICY_DESCRIPTION",effect=EFFECT, \
    principals=[PRINCIPALS],excludedPrincipals=[EXCLUDED_PRINCIPALS], \
    permissions=[eventarc.googleapis.com/messageBuses.publish], \
    activationConditions={eventarc.googleapis.com={celCondition={expression="CEL_EXPRESSION"}}}

    Ersetzen Sie Folgendes:

    • POLICY_ID: ein eindeutiger Name für die Zugriffsrichtlinie, z. B. my-access-policy.
    • POLICY_PROJECT_ID: Die Google Cloud Projekt-ID des Projekts, in dem die Richtlinie erstellt wird.
    • POLICY_DESCRIPTION: eine optionale Beschreibung der Richtlinie (maximal 256 Zeichen).
    • EFFECT: Die Wirkung der Regel (ALLOW oder DENY).
    • PRINCIPALS: Die Identitäten, auf die diese Regel angewendet wird. Das Format der ID hängt vom Typ des Hauptkontos ab, auf das Sie verweisen möchten. Weitere Informationen finden Sie unter Haupttypen für Zugriffsrichtlinien.
    • EXCLUDED_PRINCIPALS: Die Identitäten, die von der Anwendung der Regel ausgeschlossen sind, auch wenn sie in principals aufgeführt sind. Sie können beispielsweise eine Google-Gruppe zu principals hinzufügen und dann bestimmte Nutzer ausschließen, die zu dieser Gruppe gehören.
    • CEL_EXPRESSION: Der CEL-Ausdruck, der ausgewertet wird, um die Anwendbarkeit der Regel zu bestimmen, z. B. message.version != \"v1\". Weitere Informationen finden Sie unter Common Expression Language verwenden.

    Wichtige Hinweise:

    • Das Flag --location gibt den Speicherort der Zugriffsrichtlinie an und muss global sein.

    • Mit dem Flag --details-rules kann der Pfad zur Zugriffsrichtliniendatei angegeben werden, die entweder in JSON oder YAML geschrieben werden kann, z. B. --details-rules=path_to_file.json.

      Das Flag kann auch wiederholt werden, wenn mehrere Regeln konfiguriert werden. Jede Regel wird unabhängig ausgewertet.

      Eine Zugriffsrichtlinie hat das folgende Format:

      {
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ],
        "activationConditions": {
          "eventarc.googleapis.com": {
            "celCondition": {
              "expression": "CEL_EXPRESSION"
            }
          }
        }
      }
    ]
  }
}

    Die Antwort enthält einen Vorgang mit langer Ausführungszeit, der Ihre Anfrage darstellt. Informationen zum Abrufen des Status eines Vorgangs mit langer Ausführungszeit finden Sie in diesem Dokument unter Status eines Vorgangs mit langer Ausführungszeit prüfen.

    Beispiel

    Mit dem folgenden Befehl wird eine Zugriffsrichtlinie erstellt, die dem angegebenen Prinzipal das Veröffentlichen von Ereignisnachrichten in einem Bus erlaubt, aber das Veröffentlichen verweigert, wenn der Datenmediatyp JSON ist.

    gcloud beta iam access-policies create my-access-policy \
    --project=my-project-id \
    --location=global \
    --details-rules=description="Allow publishing to bus",effect=ALLOW,principals=[principal://goog/subject/user@example.com],permissions=[eventarc.googleapis.com/messageBuses.publish] \
    --details-rules=description="Deny publishing to bus if media type is JSON",effect=DENY,principals=[principal://goog/subject/user@example.com],permissions=[eventarc.googleapis.com/messageBuses.publish],activationConditions={eventarc.googleapis.com={celCondition={expression="message.datacontenttype=='application/json'"}}}

    REST API

    Sie können eine Zugriffsrichtlinie mit projects.locations.accessPolicies.create method erstellen.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • POLICY_DISPLAY_NAME: optional. Ein für Menschen lesbarer Name für die Zugriffsrichtlinie, z. B. „Beispielrichtlinie“. Der Anzeigename darf maximal 63 Zeichen lang sein.
    • POLICY_DESCRIPTION: optional. Eine menschenlesbare Beschreibung der Zugriffsrichtlinie, z. B. „Beispielbeschreibung“. Die Beschreibung darf maximal 256 Zeichen lang sein.
    • EFFECT: die Wirkung der Regel, entweder ALLOW oder DENY.
    • PRINCIPALS: Die Identitäten, auf die diese Regel angewendet wird. Das Format der ID hängt vom Typ des Hauptkontos ab, auf das Sie verweisen möchten. Weitere Informationen finden Sie unter Haupttypen für Zugriffsrichtlinien.
    • EXCLUDED_PRINCIPALS: Die Identitäten, die von der Anwendung der Regel ausgeschlossen sind, auch wenn sie in principals aufgeführt sind. Sie können beispielsweise eine Google-Gruppe zu principals hinzufügen und dann bestimmte Nutzer ausschließen, die zu dieser Gruppe gehören.
    • CEL_EXPRESSION: Der CEL-Ausdruck, der ausgewertet wird, um die Anwendbarkeit der Regel zu bestimmen. Weitere Informationen finden Sie unter Common Expression Language verwenden.
    • POLICY_PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem die Richtlinie erstellt wird.
    • POLICY_ID: ein eindeutiger Name für die Zugriffsrichtlinie, z. B. my-access-policy.

    Es können mehrere Regeln aufgeführt werden. Jede Regel wird unabhängig ausgewertet. Wenn eine Regel nicht gilt, können andere Regeln gelten.

    JSON-Text der Anfrage:

    {
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ],
        "activationConditions": {
          "eventarc.googleapis.com": {
            "celCondition": {
              "expression": "CEL_EXPRESSION"
            }
          }
        }
      }
    ]
  }
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Die Antwort enthält einen Vorgang mit langer Ausführungszeit, der Ihre Anfrage darstellt. Informationen zum Abrufen des Status eines Vorgangs mit langer Ausführungszeit finden Sie in diesem Dokument unter Status eines Vorgangs mit langer Ausführungszeit prüfen. 

    {
  "name": "projects/POLICY_PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-25T17:17:45.782370139Z",
    "target": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

    Beispiel

    Die folgende Zugriffsrichtlinie erlaubt dem angegebenen Hauptkonto, Ereignisnachrichten in einem Bus zu veröffentlichen, lehnt die Veröffentlichung jedoch ab, wenn die Nachrichtenpriorität HIGH ist.

    cat > request.json << 'EOF'
{
"displayName": "Eventarc Advanced access policy",
"details": {
  "rules": [
  {
    "description": "Allow publishing to bus",
    "effect": "ALLOW",
    "principals": [
      "principal://goog/subject/user@example.com"
    ],
    "permissions": [
      "eventarc.googleapis.com/messageBuses.publish"
    ]
  },
    {
      "description": "Deny publishing to bus if message priority is HIGH",
      "effect": "DENY",
      "principals": [
        "principal://goog/subject/user@example.com"
      ],
      "permissions": [
        "eventarc.googleapis.com/messageBuses.publish"
      ],
      "activationConditions": {
        "eventarc.googleapis.com": {
          "celCondition": {
            "expression": "message.priority == \"HIGH\""
          }
        }
      }
    }
  ]
}
}
EOF

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v3/projects/POLICY_PROJECT_ID/locations/global/accessPolicies?access_policy_id=POLICY_ID"

    Zugriffsrichtlinie anwenden

    Erstellen Sie eine Richtlinienbindung, um Ihre Zugriffsrichtlinie auf ein Google Cloud Projekt anzuwenden. Jede Richtlinienbindung verknüpft eine Zugriffsrichtlinie mit einer Ressource.

    Sie können eine Zugriffsrichtlinie mit der Google Cloud CLI oder durch eine direkte Anfrage an die IAM v3 API anwenden.

    gcloud

    Sie können eine Richtlinienbindung erstellen und Ihre Zugriffsrichtlinie anwenden, indem Sie den Befehl gcloud beta iam policy-bindings create ausführen.

    gcloud beta iam policy-bindings create BINDING_ID \
    --project=BINDING_PROJECT_ID \
    --location=global \
    --policy=projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID \
    --target-resource=//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID

    Ersetzen Sie Folgendes:

    • BINDING_ID: ein eindeutiger Name für die Richtlinienbindung, z. B. my-access-policy-binding.
    • BINDING_PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem die Bindung erstellt wird. Dies sollte dieselbe ID wie die des Projekts sein, in dem der Eventarc Advanced-Bus erstellt wird, und gibt das Ziel der Bindung an.

    Das Flag --location gibt den Speicherort der Richtlinienbindung an und muss global sein.

    Die Antwort enthält einen Vorgang mit langer Ausführungszeit, der Ihre Anfrage darstellt. Informationen zum Abrufen des Status eines Vorgangs mit langer Ausführungszeit finden Sie in diesem Dokument unter Status eines Vorgangs mit langer Ausführungszeit prüfen.

    Beispiel

    Mit dem folgenden Befehl wird eine Richtlinienbindung erstellt, mit der die angegebene Zugriffsrichtlinie auf ein Google Cloud -Projekt angewendet wird:

    gcloud beta iam policy-bindings create my-access-policy-binding \
    --project=my-project-id \
    --location=global \
    --policy=projects/my-project-id/locations/global/accessPolicies/my-access-policy \
    --target-resource=//cloudresourcemanager.googleapis.com/projects/my-project-id

    REST API

    Sie können eine Richtlinienbindung erstellen und Ihre Zugriffsrichtlinie mit projects.locations.policyBindings.create method anwenden.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • BINDING_DISPLAY_NAME: Optional. Ein für Menschen lesbarer Name für die Richtlinienbindung, z. B. „Beispielbindung“. Der Anzeigename darf maximal 63 Zeichen lang sein.
    • BINDING_PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem die Bindung erstellt wird. Dies sollte dieselbe ID wie die des Projekts sein, in dem der Eventarc Advanced-Bus erstellt wird, und das Ziel der Bindung angeben.
    • POLICY_PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem die Richtlinie erstellt wird.
    • POLICY_ID: Der Name der zu bindenden Zugriffsrichtlinie, z. B. my-access-policy.

    JSON-Text der Anfrage:

    {
  "display_name": "BINDING_DISPLAY_NAME",
  "target": {"resource": "//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID"},
  "policy_kind": "ACCESS",
  "policy": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID"
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Die Antwort enthält einen Vorgang mit langer Ausführungszeit, der Ihre Anfrage darstellt. Informationen zum Abrufen des Status eines Vorgangs mit langer Ausführungszeit finden Sie auf dieser Seite unter Status eines Vorgangs mit langer Ausführungszeit prüfen. 

    {
  "name": "projects/BINDING_PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-25T17:17:45.782370139Z",
    "target": "projects/BINDING_PROJECT_ID/locations/global/policyBindings/POLICY_ID-binding",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

    Status eines Vorgangs mit langer Ausführungszeit prüfen

    Wenn Sie die IAM REST API verwenden, gibt jede Methode, die eine Zugriffsrichtlinie oder ‑bindung ändert, einen Vorgang mit langer Ausführungszeit (long-running operation, LRO) zurück. Der Vorgang mit langer Ausführungszeit verfolgt den Status der Anfrage und gibt an, ob die Änderung der Richtlinie oder Bindung abgeschlossen ist.

    Die Methode operations.get gibt den Status eines Vorgang mit langer Ausführungszeit zurück.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • OPERATION_NAME: Der vollständige Name des Vorgangs. Sie erhalten diesen Namen in der Antwort auf Ihre ursprüngliche Anfrage.

      Der Vorgangsname hat das folgende Format: 

      projects/PROJECT_ID/locations/global/operations/OPERATION_ID
    • PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem der Vorgang zurückgegeben wird.

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    {
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-28T00:05:12.006289686Z",
    "endTime": "2025-01-28T00:05:12.192141801Z",
    "target": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": true,
  "response": {
    ACCESS_POLICY
  }
}

    Wenn das Feld done des Vorgangs nicht vorhanden ist, überwachen Sie seinen Status, indem Sie den Vorgang wiederholt abrufen. Verwenden Sie den abgeschnittenen exponentiellen Backoff, um zwischen jeder Anfrage eine Verzögerung einzuführen. Wenn das Feld done auf true gesetzt ist, ist der Vorgang abgeschlossen und Sie können den Vorgang beenden.

    Nächste Schritte