Passer au contenu

Cette page a été traduite automatiquement et peut contenir des inexactitudes. Pour signaler une erreur de traduction, utilisez le module de commentaires en bas de la table des matières, à droite de la page.

Configurer Google Cloud pour Workload Identity Federation

Cette page explique comment configurer votre projet Google Cloud afin que l’ingestion de données cloud (CDI) de Braze puisse accéder à BigQuery et Google Cloud Storage (GCS) avec Workload Identity Federation (WIF). Pour le reste de la configuration de la source, consultez Intégrations d’entrepôts de données, Sources connectées ou Intégrations de stockage de fichiers.

Avec WIF, Braze s’authentifie auprès de Google Cloud à l’aide d’une identité éphémère provenant de son propre environnement AWS, puis usurpe l’identité d’un compte de service dans votre projet. Vous configurez votre projet pour faire confiance à cette identité uniquement pour votre espace de travail. Vous ne créez ni ne partagez de clé de compte de service.

Vous configurez WIF une seule fois par projet Google Cloud. Un seul identifiant WIF dessert à la fois les sources BigQuery et GCS, donc si vous avez déjà effectué ces étapes pour l’une d’entre elles, accordez au compte de service existant l’accès aux nouvelles données à l’étape 6 et ignorez le reste.

Prérequis

Pour effectuer ces étapes dans la console Google Cloud, vous devez disposer des autorisations nécessaires pour créer des pools d’identités de charge de travail et des comptes de service, ainsi que pour gérer les politiques Identity and Access Management (IAM) sur le compte de service et vos données. Par exemple, vous pouvez utiliser les rôles Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) et Service Account Admin (roles/iam.serviceAccountAdmin).

Ne faire confiance qu’au principal de votre espace de travail

Avertissement

Accordez l’accès à l’Amazon Resource Name (ARN) complet du principal Braze provenant de votre formulaire d’identifiant. N’accordez pas l’accès au rôle AWS de Braze ni au compte AWS. Un accès au niveau du rôle ou du compte permet à d’autres clients Braze de lire vos données.

Chaque espace de travail Braze sur la même instance Braze présente le même rôle AWS. Seul le nom de session à la fin de l’ARN du principal, qui correspond à l’identifiant de votre espace de travail, vous est unique.

Le mappage d’attributs par défaut de Google pour les fournisseurs AWS définit aws_role comme l’ARN du rôle sans le nom de session. Cela signifie qu’accorder l’accès aux identités correspondant à une valeur aws_role, comme principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, fait confiance à chaque espace de travail Braze sur votre instance, y compris le vôtre.

Pour limiter l’accès à vos données à votre espace de travail :

Accordez l’accès uniquement aux identités dont le subject est l’ARN complet de votre principal Braze. Il s’agit du principal principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN.
N’accordez pas l’accès à Toutes les identités du pool, ni aux identités filtrées par aws_role ou account.
N’écrivez pas de condition d’attribut qui vérifie uniquement le compte AWS ou le rôle.
Conservez le mappage d’attributs par défaut pour google.subject, qui est assertion.arn.

L’ARN du principal Braze diffère pour chaque espace de travail et chaque instance Braze, et Braze utilise un rôle AWS distinct pour les sources Google par rapport à d’autres sources comme Snowflake. Copiez toujours la valeur depuis un formulaire d’identifiant BigQuery ou GCS dans l’espace de travail que vous connectez.

Configuration de Workload Identity Federation

Étape 1 : copier l’ARN du principal Braze

Dans Braze, commencez à créer votre source BigQuery ou GCS et sélectionnez Workload Identity Federation comme méthode d’authentification. Copiez la valeur à l’étape 1 du formulaire d’identifiant, Copy the Braze principal ARN, et laissez le formulaire ouvert.

Si le champ affiche Unavailable, WIF n’est pas disponible pour votre instance Braze. Utilisez plutôt une clé de compte de service.

Étape 2 : activer les API requises

Dans la console Google Cloud, accédez à APIs & Services > Library et activez les API suivantes pour votre projet :

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

Étape 3 : créer le pool d’identités de charge de travail et le fournisseur

Accédez à IAM & Admin > Workload Identity Federation, puis sélectionnez Create pool.
Saisissez un nom pour le pool, par exemple « Braze CDI ». Notez le Pool ID, puis sélectionnez Continue.
Pour Select a provider, sélectionnez AWS.
Saisissez un nom de fournisseur, par exemple « Braze AWS », et notez le Provider ID.
Pour AWS account ID, saisissez le nombre à 12 chiffres qui suit arn:aws:sts:: dans l’ARN du principal Braze, puis sélectionnez Continue.
Sous Configure provider attributes, conservez le mappage par défaut, y compris google.subject = assertion.arn.
Sélectionnez Save.

Les identifiants de pool et de fournisseur doivent contenir de 4 à 32 caractères, en utilisant des lettres minuscules, des chiffres et des tirets.

Restreindre le fournisseur à votre principal (facultatif)

Pour une défense en profondeur, ajoutez une condition d’attribut afin que le fournisseur n’accepte que le principal de votre espace de travail. Google rejettera alors toute autre identité lors de l’échange de jetons, avant même de vérifier les autorisations du compte de service.

Dans le pool, sélectionnez le fournisseur, puis sélectionnez Edit.
Sous Attribute conditions, sélectionnez Add condition.

Saisissez la condition suivante, en remplaçant BRAZE_PRINCIPAL_ARN par la valeur complète copiée à l’étape 1 :

 assertion.arn == 'BRAZE_PRINCIPAL_ARN'

Sélectionnez Save.

Cette condition dédie le fournisseur à un seul espace de travail Braze. Pour connecter un autre espace de travail, créez un fournisseur distinct ou listez les deux principaux, comme dans assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].

Étape 4 : créer le compte de service

Si vous disposez déjà d’un compte de service pour Braze, par exemple un compte issu de la configuration GCS, ignorez cette étape.

Accédez à IAM & Admin > Service Accounts, puis sélectionnez Create service account.
Saisissez un nom, par exemple « Braze CDI », puis sélectionnez Create and continue.
Ignorez les étapes facultatives de rôle de projet et d’accès utilisateur, puis sélectionnez Done. Vous accorderez l’accès aux données à l’étape 6.

Étape 5 : lier le principal Braze au compte de service

Accordez au principal de votre espace de travail la permission d’usurper l’identité du compte de service :

Accédez à IAM & Admin > Workload Identity Federation, puis sélectionnez votre pool.
Sélectionnez Grant access, puis Grant access using service account impersonation.
Pour Service account, sélectionnez le compte de service de l’étape 4.
Sous Select principals, sélectionnez Only identities matching the filter.
Pour Attribute name, sélectionnez subject. Pour Attribute value, collez l’ARN complet du principal Braze de l’étape 1.
Sélectionnez Save. Si Google vous propose de télécharger un fichier de configuration de bibliothèque cliente, sélectionnez Dismiss. Braze n’en a pas besoin.

Ceci accorde le rôle Workload Identity User (roles/iam.workloadIdentityUser) sur le compte de service à un principal sous cette forme :

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

Pour confirmer, ouvrez le compte de service et sélectionnez l’onglet Permissions. Le rôle Workload Identity User devrait lister ce principal, se terminant par l’ARN complet de votre principal Braze.

Avertissement

Ne sélectionnez pas All identities in the pool et ne filtrez pas par aws_role. Les deux correspondent à chaque espace de travail Braze sur votre instance Braze, car ils partagent tous le même rôle AWS. Pour plus de détails, consultez Ne faire confiance qu’au principal de votre espace de travail.

Accordez ce rôle uniquement sur le compte de service. Un accord au niveau du projet permet au principal d’usurper l’identité de chaque compte de service du projet.

Les modifications IAM peuvent prendre quelques minutes pour prendre effet. Si un test de connexion échoue juste après avoir accordé l’accès, attendez quelques minutes et réessayez.

Étape 6 : accorder au compte de service l’accès à vos données

Accordez au compte de service les autorisations pour votre source :

BigQuery : les rôles BigQuery de l’étape 1.2 des Intégrations d’entrepôts de données, ou de l’étape 2.1 des Sources connectées
Google Cloud Storage : les autorisations de compartiment et d’abonnement dans Attribuer les autorisations

Si vous utilisez un identifiant pour les deux sources, accordez les deux ensembles d’autorisations au même compte de service.

Étape 7 : saisir les valeurs dans Braze

Retournez au formulaire d’identifiant Braze et saisissez les valeurs suivantes depuis la console Google Cloud :

Champ Braze	Où le trouver
Project number	La carte Project info sur le Dashboard de la console. Utilisez le numéro de projet numérique plutôt que l’identifiant du projet.
Workload identity pool ID	Le Pool ID de l’étape 3
Provider ID	Le Provider ID de l’étape 3
Service account email	L’Email du compte de service sur la page Service Accounts

Braze combine le numéro de projet, l’identifiant du pool et l’identifiant du fournisseur en une audience, qui indique à Google quel fournisseur valide la requête provenant de Braze. Par défaut, un fournisseur accepte son propre nom de ressource comme audience. Si vous définissez des audiences autorisées personnalisées sur votre fournisseur, incluez le nom de ressource complet du fournisseur.

Étape 8 : tester la connexion

Lorsque vous testez la connexion dans Braze, Braze vérifie également que votre configuration ne fait confiance qu’à votre espace de travail. Pendant le test, Braze tente le même échange avec un nom de session de test composé uniquement de zéros, sous cette forme :

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

Votre configuration doit rejeter cette identité, soit lors de l’échange de jetons, soit lorsqu’elle tente d’usurper l’identité de votre compte de service. Si les deux étapes réussissent, le test échoue, car votre configuration fait confiance à des identités autres que le principal de votre espace de travail. Pour corriger cela, consultez la section Votre configuration fait confiance à des identités autres que votre espace de travail.

Si vous avez défini la condition d’attribut facultative, Google rejette l’identité de test lors de l’échange de jetons. Sinon, Google rejette l’identité de test lorsque celle-ci tente d’usurper l’identité de votre compte de service. Dans les deux cas, le test réussit.

Vous pouvez voir cette tentative rejetée dans vos journaux d’audit Google Cloud à chaque test de connexion. Ce comportement est attendu. La tentative provient de la vérification de Braze et ne donne à personne accès à vos données.

N’ajoutez pas de condition qui rejette uniquement cette session de test. Une telle condition fait réussir le test alors que votre configuration fait encore confiance à d’autres espaces de travail Braze.

Supprimer l’accès de Braze

Pour empêcher Braze d’accéder à vos données, supprimez le rôle Workload Identity User du principal Braze dans l’onglet Permissions du compte de service, ou supprimez le fournisseur.

Configuration avec la CLI gcloud

Si vous préférez la ligne de commande, les commandes suivantes complètent les étapes 2 à 5. Remplacez les valeurs dans le premier bloc et collez l’ARN du principal Braze exactement tel que copié.

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

Résolution des problèmes

Votre configuration fait confiance à des identités autres que votre espace de travail

Le test de connexion échoue avec l’erreur suivante :

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.

Cela signifie que Google a accepté l’identité de test de Braze à la fois lors de l’échange de jetons et lors de l’usurpation du compte de service, comme décrit à l’étape 8. Cette erreur se produit généralement lorsque le compte de service accorde l’accès à toutes les identités du pool ou aux identités filtrées par aws_role.

Pour corriger cette erreur :

Dans la console Google Cloud, ouvrez le compte de service et sélectionnez l’onglet Permissions.
Recherchez chaque principal ayant le rôle Workload Identity User qui commence par principalSet:// et référence votre pool. Supprimez le rôle de chacun.
Assurez-vous que votre principal complet dispose du rôle, comme à l’étape 5.
Accédez à IAM & Admin > IAM et vérifiez les accords Workload Identity User au niveau du projet pour votre pool. Supprimez-les.
Testez à nouveau la connexion.

Vous pouvez aussi restreindre la condition d’attribut du fournisseur à votre principal complet, comme décrit dans Restreindre le fournisseur à votre principal (facultatif). Google rejettera alors toute autre identité lors de l’échange de jetons. Nous recommandons tout de même d’accorder l’accès uniquement à votre principal complet.

Braze n’a pas pu confirmer que votre pool ne fait confiance qu’à cet espace de travail

Le test de connexion échoue avec l’erreur suivante :

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.

La vérification de Braze à l’étape 8 n’a pas abouti à un résultat. Par exemple, une erreur réseau ou une erreur temporaire de Google Cloud a interrompu la vérification. Cette erreur ne signifie pas que votre configuration est trop large. Testez à nouveau la connexion. Si l’erreur persiste, contactez le support Braze.

Autorisation refusée lorsque Braze usurpe l’identité du compte de service

Le test de connexion échoue avec une erreur d’autorisation sur iam.serviceAccounts.getAccessToken. Vérifiez les points suivants :

L’onglet Permissions du compte de service liste le rôle Workload Identity User pour un principal se terminant par l’ARN complet de votre principal Braze, copié depuis un formulaire d’identifiant BigQuery ou GCS dans le même espace de travail.
L’API IAM Service Account Credentials est activée.
Vous avez attendu quelques minutes depuis l’accord de l’accès.

L’échange de jetons est rejeté

Le test de connexion échoue au niveau de l’échange de jetons Google Security Token Service. Vérifiez les points suivants :

Le numéro de projet, l’identifiant du pool et l’identifiant du fournisseur que vous avez saisis dans Braze correspondent à votre configuration Google Cloud.
L’identifiant de compte AWS du fournisseur correspond à l’identifiant de compte dans l’ARN du principal Braze.
Si vous avez défini une condition d’attribut, elle contient l’ARN complet de votre principal, exactement tel que copié.
Si vous avez défini des audiences autorisées personnalisées, elles incluent le nom de ressource complet du fournisseur.
Le pool et le fournisseur sont activés.

New Stuff!