Zum Inhalt springen

Diese Seite wurde automatisch übersetzt und kann Ungenauigkeiten enthalten. Um einen Übersetzungsfehler zu melden, nutzen Sie das Feedback unten im Inhaltsverzeichnis rechts auf der Seite.

Google Cloud für Workload Identity Federation konfigurieren

Diese Seite beschreibt, wie Sie Ihr Google-Cloud-Projekt konfigurieren, damit die Braze-Datenaufnahme aus der Cloud (CDI) mit Workload Identity Federation (WIF) auf BigQuery und Google Cloud Storage (GCS) zugreifen kann. Den Rest der Quelleneinrichtung finden Sie unter Data-Warehouse-Integrationen, Verbundene Quellen oder Dateispeicher-Integrationen.

Mit WIF authentifiziert sich Braze bei Google Cloud mit einer kurzlebigen Identität aus der eigenen AWS-Umgebung und nimmt dann in Ihrem Projekt die Identität eines Dienstkontos an. Sie konfigurieren Ihr Projekt so, dass es dieser Identität nur für Ihren Workspace vertraut. Sie erstellen oder teilen keinen Dienstkontoschlüssel.

Sie richten WIF einmal pro Google-Cloud-Projekt ein. Eine WIF-Zugangsberechtigung bedient sowohl BigQuery- als auch GCS-Quellen. Wenn Sie diese Schritte also bereits für eine Quelle abgeschlossen haben, gewähren Sie dem vorhandenen Dienstkonto in Schritt 6 Zugriff auf die neuen Daten und überspringen den Rest.

Voraussetzungen

Um diese Schritte in der Google-Cloud-Konsole auszuführen, benötigen Sie die Berechtigung, Workload-Identity-Pools und Dienstkonten zu erstellen sowie Identity-and-Access-Management-Richtlinien (IAM) für das Dienstkonto und Ihre Daten zu verwalten. Sie können beispielsweise die Rollen Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) und Service Account Admin (roles/iam.serviceAccountAdmin) verwenden.

Nur dem Principal Ihres Workspace vertrauen

Warnung

Gewähren Sie Zugriff auf den vollständigen Braze-Principal-Amazon-Resource-Name (ARN) aus Ihrem Zugangsdatenformular. Gewähren Sie keinen Zugriff auf die Braze-AWS-Rolle oder das Braze-AWS-Konto. Eine Berechtigung auf Rollen- oder Kontoebene ermöglicht es anderen Braze-Kund:innen, Ihre Daten zu lesen.

Jeder Braze-Workspace auf derselben Braze-Instanz verwendet dieselbe AWS-Rolle. Nur der Sitzungsname am Ende des Principal-ARN, der Ihre Workspace-ID ist, ist eindeutig für Sie.

Googles Standard-Attribut-Mapping für AWS-Anbieter setzt aws_role auf den Rollen-ARN ohne den Sitzungsnamen. Das bedeutet, dass das Gewähren von Zugriff auf Identitäten, die einem aws_role-Wert entsprechen – wie principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN – jedem Braze-Workspace auf Ihrer Instanz vertraut, einschließlich Ihrem.

Um Ihre Daten auf Ihren Workspace zu beschränken:

Gewähren Sie Zugriff nur auf Identitäten, deren subject Ihr vollständiger Braze-Principal-ARN ist. Das ist der Principal principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN.
Gewähren Sie keinen Zugriff auf Alle Identitäten im Pool oder auf Identitäten, die nach aws_role oder account gefiltert werden.
Schreiben Sie keine Attributbedingung, die nur das AWS-Konto oder die AWS-Rolle prüft.
Behalten Sie das Standard-Attribut-Mapping für google.subject bei, also assertion.arn.

Der Braze-Principal-ARN unterscheidet sich je Workspace und Braze-Instanz, und Braze verwendet für Google-Quellen eine andere AWS-Rolle als für andere Quellen wie Snowflake. Kopieren Sie den Wert immer aus einem BigQuery- oder GCS-Zugangsdatenformular in dem Workspace, den Sie verbinden.

Workload Identity Federation einrichten

Schritt 1: Den Braze-Principal-ARN kopieren

Beginnen Sie in Braze mit dem Erstellen Ihrer BigQuery- oder GCS-Quelle und wählen Sie Workload Identity Federation als Authentifizierungsmethode. Kopieren Sie den Wert in Schritt 1 des Zugangsdatenformulars, Copy the Braze principal ARN, und lassen Sie das Formular geöffnet.

Wenn das Feld Unavailable anzeigt, ist WIF für Ihre Braze-Instanz nicht verfügbar. Verwenden Sie stattdessen einen Dienstkontoschlüssel.

Schritt 2: Die erforderlichen APIs aktivieren

Gehen Sie in der Google-Cloud-Konsole zu APIs & Services > Library und aktivieren Sie die folgenden APIs für Ihr Projekt:

IAM Service Account Credentials API
Security Token Service API
Identity and Access Management (IAM) API

Schritt 3: Workload-Identity-Pool und -Anbieter erstellen

Gehen Sie zu IAM & Admin > Workload Identity Federation und wählen Sie Create pool.
Geben Sie einen Namen für den Pool ein, z. B. „Braze CDI“. Notieren Sie die Pool-ID und wählen Sie Continue.
Wählen Sie unter Select a provider die Option AWS.
Geben Sie einen Anbieternamen ein, z. B. „Braze AWS“, und notieren Sie die Provider-ID.
Geben Sie unter AWS account ID die 12-stellige Nummer ein, die im Braze-Principal-ARN auf arn:aws:sts:: folgt, und wählen Sie Continue.
Behalten Sie unter Configure provider attributes das Standard-Mapping bei, einschließlich google.subject = assertion.arn.
Wählen Sie Save.

Pool- und Provider-IDs müssen 4 bis 32 Zeichen umfassen und dürfen nur Kleinbuchstaben, Zahlen und Bindestriche enthalten.

Anbieter auf Ihren Principal beschränken (optional)

Fügen Sie als zusätzliche Sicherheitsebene eine Attributbedingung hinzu, damit der Anbieter nur den Principal Ihres Workspace akzeptiert. Google lehnt dann jede andere Identität beim Token-Austausch ab, bevor Google irgendeine Dienstkontoberechtigung prüft.

Wählen Sie im Pool den Anbieter aus und dann Edit.
Wählen Sie unter Attribute conditions die Option Add condition.
Geben Sie die folgende Bedingung ein und ersetzen Sie BRAZE_PRINCIPAL_ARN durch den vollständigen Wert, den Sie in Schritt 1 kopiert haben:
```
1

 assertion.arn == 'BRAZE_PRINCIPAL_ARN'
```
Wählen Sie Save.

Diese Bedingung widmet den Anbieter einem einzelnen Braze-Workspace. Um einen weiteren Workspace zu verbinden, erstellen Sie einen separaten Anbieter dafür oder listen Sie beide Principals auf, z. B. assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].

Schritt 4: Dienstkonto erstellen

Wenn Sie bereits ein Dienstkonto für Braze haben, z. B. eines aus der GCS-Einrichtung, überspringen Sie diesen Schritt.

Gehen Sie zu IAM & Admin > Service Accounts und wählen Sie Create service account.
Geben Sie einen Namen ein, z. B. „Braze CDI“, und wählen Sie Create and continue.
Überspringen Sie die optionalen Schritte für Projektrolle und Nutzer:innenzugriff und wählen Sie Done. Sie gewähren den Datenzugriff in Schritt 6.

Schritt 5: Braze-Principal an das Dienstkonto binden

Gewähren Sie dem Principal Ihres Workspace die Berechtigung, die Identität des Dienstkontos anzunehmen:

Gehen Sie zu IAM & Admin > Workload Identity Federation und wählen Sie Ihren Pool aus.
Wählen Sie Grant access und dann Grant access using service account impersonation.
Wählen Sie unter Service account das Dienstkonto aus Schritt 4.
Wählen Sie unter Select principals die Option Only identities matching the filter.
Wählen Sie unter Attribute name den Wert subject. Fügen Sie unter Attribute value den vollständigen Braze-Principal-ARN aus Schritt 1 ein.
Wählen Sie Save. Wenn Google anbietet, eine Client-Bibliotheks-Konfigurationsdatei herunterzuladen, wählen Sie Dismiss. Braze benötigt diese nicht.

Dadurch wird die Rolle Workload Identity User (roles/iam.workloadIdentityUser) auf dem Dienstkonto einem Principal in dieser Form gewährt:

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN

Öffnen Sie zur Bestätigung das Dienstkonto und wählen Sie den Tab Permissions. Die Rolle Workload Identity User sollte diesen Principal auflisten, endend mit Ihrem vollständigen Braze-Principal-ARN.

Warnung

Wählen Sie nicht All identities in the pool und filtern Sie nicht nach aws_role. Beides stimmt mit jedem Braze-Workspace auf Ihrer Braze-Instanz überein, da alle dieselbe AWS-Rolle verwenden. Weitere Informationen finden Sie unter Nur dem Principal Ihres Workspace vertrauen.

Gewähren Sie diese Rolle nur auf dem Dienstkonto. Eine Berechtigung auf Projektebene ermöglicht es dem Principal, die Identität jedes Dienstkontos im Projekt anzunehmen.

IAM-Änderungen können einige Minuten dauern, bis sie wirksam werden. Wenn ein Verbindungstest unmittelbar nach der Zugriffsvergabe fehlschlägt, warten Sie einige Minuten und versuchen Sie es erneut.

Schritt 6: Dem Dienstkonto Zugriff auf Ihre Daten gewähren

Gewähren Sie dem Dienstkonto die Berechtigungen für Ihre Quelle:

BigQuery: Die BigQuery-Rollen in Schritt 1.2 der Data-Warehouse-Integrationen oder in Schritt 2.1 der Verbundenen Quellen
Google Cloud Storage: Die Bucket- und Abo-Berechtigungen unter Berechtigungen zuweisen

Wenn Sie eine Zugangsberechtigung für beide Quellen verwenden, gewähren Sie beide Berechtigungssätze demselben Dienstkonto.

Schritt 7: Die Werte in Braze eingeben

Kehren Sie zum Braze-Zugangsdatenformular zurück und geben Sie die folgenden Werte aus der Google-Cloud-Konsole ein:

Braze-Feld	Wo Sie es finden
Project number	Die Karte Project info auf dem Konsolen-Dashboard. Verwenden Sie die numerische Projektnummer, nicht die Projekt-ID.
Workload identity pool ID	Die Pool-ID aus Schritt 3
Provider ID	Die Provider-ID aus Schritt 3
Service account email	Die E-Mail des Dienstkontos auf der Seite Service Accounts

Braze kombiniert Projektnummer, Pool-ID und Provider-ID zur Audience, die Google mitteilt, welcher Anbieter die Anfrage von Braze validiert. Standardmäßig akzeptiert ein Anbieter seinen eigenen Ressourcennamen als Audience. Wenn Sie benutzerdefinierte zulässige Audiences für Ihren Anbieter festgelegt haben, fügen Sie den vollständigen Ressourcennamen des Anbieters hinzu.

Schritt 8: Die Verbindung testen

Wenn Sie die Verbindung in Braze testen, prüft Braze auch, ob Ihre Konfiguration nur Ihrem Workspace vertraut. Während des Tests versucht Braze denselben Austausch mit einem Test-Sitzungsnamen aus lauter Nullen in dieser Form:

assumed-role/cdi-gcs-bigquery-sync-<deployment>/000000000000000000000000

Ihre Konfiguration muss diese Identität ablehnen, entweder beim Token-Austausch oder wenn sie versucht, die Identität Ihres Dienstkontos anzunehmen. Wenn beide Schritte erfolgreich sind, schlägt der Test fehl, da Ihre Konfiguration anderen Identitäten als dem Principal Ihres Workspace vertraut. Um dies zu beheben, lesen Sie den Abschnitt Ihre Konfiguration vertraut anderen Identitäten als Ihrem Workspace.

Wenn Sie die optionale Attributbedingung festgelegt haben, lehnt Google die Testidentität beim Token-Austausch ab. Andernfalls lehnt Google die Testidentität ab, wenn sie versucht, die Identität Ihres Dienstkontos anzunehmen. In beiden Fällen ist der Test bestanden.

Möglicherweise sehen Sie diesen abgelehnten Versuch in Ihren Google-Cloud-Audit-Logs jedes Mal, wenn Sie die Verbindung testen. Dieses Verhalten ist erwartet. Der Versuch stammt von der Braze-Prüfung und gewährt niemandem Zugriff auf Ihre Daten.

Fügen Sie keine Bedingung hinzu, die nur diese Testsitzung ablehnt. Eine solche Bedingung besteht den Test, während Ihre Konfiguration weiterhin anderen Braze-Workspaces vertraut.

Braze-Zugriff entfernen

Um zu verhindern, dass Braze auf Ihre Daten zugreift, entfernen Sie die Rolle Workload Identity User für den Braze-Principal über den Tab Permissions des Dienstkontos oder löschen Sie den Anbieter.

Einrichtung mit der gcloud-CLI

Wenn Sie die Befehlszeile bevorzugen, führen die folgenden Befehle die Schritte 2 bis 5 aus. Ersetzen Sie die Werte im ersten Block und fügen Sie den Braze-Principal-ARN genau so ein, wie Sie ihn kopiert haben.

PROJECT_ID="YOUR-PROJECT-ID"
POOL_ID="braze-cdi"
PROVIDER_ID="braze-aws"
SA_NAME="braze-cdi"
BRAZE_PRINCIPAL_ARN="PASTE-THE-BRAZE-PRINCIPAL-ARN-FROM-YOUR-CREDENTIAL-FORM"

PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
BRAZE_AWS_ACCOUNT_ID="$(echo "$BRAZE_PRINCIPAL_ARN" | cut -d: -f5)"
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud services enable iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
  --project="$PROJECT_ID"

gcloud iam workload-identity-pools create "$POOL_ID" \
  --project="$PROJECT_ID" --location="global" --display-name="Braze CDI"

gcloud iam workload-identity-pools providers create-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --account-id="$BRAZE_AWS_ACCOUNT_ID"

# Optional: restrict the provider to your principal
gcloud iam workload-identity-pools providers update-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --attribute-condition="assertion.arn == '${BRAZE_PRINCIPAL_ARN}'"

# Skip if you already have a service account for Braze
gcloud iam service-accounts create "$SA_NAME" \
  --project="$PROJECT_ID" --display-name="Braze CDI"

gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --project="$PROJECT_ID" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${BRAZE_PRINCIPAL_ARN}"

Fehlerbehebung

Ihre Konfiguration vertraut anderen Identitäten als Ihrem Workspace

Der Verbindungstest schlägt mit dem folgenden Fehler fehl:

Your workload identity pool trusts every Braze customer, not only this workspace. Braze authenticated against it with a test identity (000000000000000000000000) that belongs to no Braze workspace, and your Google Cloud project accepted it, so another Braze customer could read this data. Grant the Workload Identity User role on your service account to the full Braze principal shown on the credential screen (principal://…/subject/<full ARN>) rather than to the role (principalSet://…/attribute.aws_role/…); restricting the pool provider’s attribute condition to that same principal works as well. Then test the connection again.

Das bedeutet, dass Google die Braze-Testidentität sowohl beim Token-Austausch als auch beim Identitätswechsel des Dienstkontos akzeptiert hat, wie in Schritt 8 beschrieben. Dieser Fehler tritt in der Regel auf, wenn das Dienstkonto allen Identitäten im Pool oder nach aws_role gefilterten Identitäten Zugriff gewährt.

Um diesen Fehler zu beheben:

Öffnen Sie in der Google-Cloud-Konsole das Dienstkonto und wählen Sie den Tab Permissions.
Suchen Sie jeden Principal mit der Rolle Workload Identity User, der mit principalSet:// beginnt und auf Ihren Pool verweist. Entfernen Sie die Rolle von jedem dieser Einträge.
Stellen Sie sicher, dass Ihr vollständiger Principal die Rolle hat, wie in Schritt 5 beschrieben.
Gehen Sie zu IAM & Admin > IAM und prüfen Sie, ob es Berechtigungen für Workload Identity User auf Projektebene für Ihren Pool gibt. Entfernen Sie diese.
Testen Sie die Verbindung erneut.

Alternativ können Sie die Attributbedingung des Anbieters auf Ihren vollständigen Principal beschränken, wie unter Anbieter auf Ihren Principal beschränken (optional) beschrieben. Google lehnt dann jede andere Identität beim Token-Austausch ab. Wir empfehlen dennoch, den Zugriff nur Ihrem vollständigen Principal zu gewähren.

Braze konnte nicht bestätigen, dass Ihr Pool nur diesem Workspace vertraut

Der Verbindungstest schlägt mit dem folgenden Fehler fehl:

Braze could not confirm that your workload identity pool trusts only this workspace. The check needs Google to explicitly refuse an identity that is not yours, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.

Die Braze-Prüfung in Schritt 8 kam zu keinem Ergebnis. Beispielsweise hat ein Netzwerkfehler oder ein vorübergehender Google-Cloud-Fehler die Prüfung unterbrochen. Dieser Fehler bedeutet nicht, dass Ihre Konfiguration zu breit gefasst ist. Testen Sie die Verbindung erneut. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Braze-Support.

Zugriff verweigert, wenn Braze die Identität des Dienstkontos annimmt

Der Verbindungstest schlägt mit einem Berechtigungsfehler für iam.serviceAccounts.getAccessToken fehl. Prüfen Sie Folgendes:

Der Tab Permissions des Dienstkontos listet die Rolle Workload Identity User für einen Principal auf, der mit Ihrem vollständigen Braze-Principal-ARN endet, kopiert aus einem BigQuery- oder GCS-Zugangsdatenformular im selben Workspace.
Die IAM Service Account Credentials API ist aktiviert.
Sie haben seit der Zugriffsvergabe einige Minuten gewartet.

Der Token-Austausch wird abgelehnt

Der Verbindungstest schlägt beim Google Security Token Service Token-Austausch fehl. Prüfen Sie Folgendes:

Die Projektnummer, Pool-ID und Provider-ID, die Sie in Braze eingegeben haben, stimmen mit Ihrer Google-Cloud-Konfiguration überein.
Die AWS-Konto-ID des Anbieters stimmt mit der Konto-ID im Braze-Principal-ARN überein.
Wenn Sie eine Attributbedingung festgelegt haben, enthält sie Ihren vollständigen Principal-ARN, genau wie kopiert.
Wenn Sie benutzerdefinierte zulässige Audiences festgelegt haben, enthalten sie den vollständigen Ressourcennamen des Anbieters.
Pool und Anbieter sind aktiviert.

New Stuff!