Ir para o conteúdo

Esta página foi traduzida automaticamente e pode conter imprecisões. Para relatar um erro de tradução, use o componente de feedback na parte inferior do sumário, à direita da página.

Configurando o Google Cloud para Workload Identity Federation

Esta página explica como configurar seu projeto do Google Cloud para que a ingestão de dados na nuvem (CDI) da Braze acesse o BigQuery e o Google Cloud Storage (GCS) com o Workload Identity Federation (WIF). Para o restante da configuração da fonte, consulte Integrações de data warehouse, Fontes conectadas ou Integrações de armazenamento de arquivos.

Com o WIF, a Braze se autentica no Google Cloud com uma identidade de curta duração do próprio ambiente AWS e, em seguida, assume a identidade de uma conta de serviço no seu projeto. Você configura o projeto para confiar nessa identidade apenas para o seu espaço de trabalho. Não é necessário criar nem compartilhar uma chave de conta de serviço.

A configuração do WIF é feita uma vez por projeto do Google Cloud. Uma credencial WIF atende tanto a fontes do BigQuery quanto do GCS. Portanto, se você já concluiu essas etapas para uma fonte, basta conceder à conta de serviço existente acesso aos novos dados na Etapa 6 e pular o restante.

Pré-requisitos

Para concluir essas etapas no console do Google Cloud, você precisa de permissão para criar pools de identidade de carga de trabalho e contas de serviço, e para gerenciar políticas de Identity and Access Management (IAM) na conta de serviço e nos seus dados. Por exemplo, você pode usar as funções Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) e Service Account Admin (roles/iam.serviceAccountAdmin).

Confie apenas no principal do seu espaço de trabalho

Aviso

Conceda acesso ao Amazon Resource Name (ARN) principal completo da Braze no seu formulário de credenciais. Não conceda acesso à função AWS ou à conta AWS da Braze. Uma concessão no nível de função ou conta permite que outros clientes da Braze leiam seus dados.

Todos os espaços de trabalho da Braze na mesma instância da Braze apresentam a mesma função AWS. Apenas o nome da sessão no final do ARN principal, que é o ID do seu espaço de trabalho, é exclusivo para você.

O mapeamento de atributos padrão do Google para provedores AWS define aws_role como o ARN da função sem o nome da sessão. Isso significa que conceder acesso a identidades que correspondem a um valor aws_role, como principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, confia em todos os espaços de trabalho da Braze na sua instância, incluindo o seu.

Para manter seus dados restritos ao seu espaço de trabalho:

Conceda acesso apenas a identidades cujo subject é o ARN principal completo da Braze. Esse é o principal principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN.
Não conceda acesso a All identities in the pool, nem a identidades filtradas por aws_role ou account.
Não escreva uma condição de atributo que verifique apenas a conta ou função AWS.
Mantenha o mapeamento de atributo padrão para google.subject, que é assertion.arn.

O ARN principal da Braze é diferente para cada espaço de trabalho e instância da Braze, e a Braze usa uma função AWS separada para fontes do Google do que para outras fontes, como o Snowflake. Sempre copie o valor de um formulário de credenciais do BigQuery ou GCS no espaço de trabalho que você está conectando.

Configurando o Workload Identity Federation

Etapa 1: copie o ARN principal da Braze

Na Braze, comece a criar sua fonte do BigQuery ou GCS e selecione Workload Identity Federation como método de autenticação. Copie o valor na etapa 1 do formulário de credenciais, Copy the Braze principal ARN, e mantenha o formulário aberto.

Se o campo mostrar Unavailable, o WIF não está disponível para a sua instância da Braze. Use uma chave de conta de serviço.

Etapa 2: ative as APIs necessárias

No console do Google Cloud, acesse APIs & Services > Library e ative as seguintes APIs para o seu projeto:

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

Etapa 3: crie o pool e o provedor de identidade de carga de trabalho

Acesse IAM & Admin > Workload Identity Federation e selecione Create pool.
Insira um nome para o pool, como “Braze CDI”. Anote o Pool ID e selecione Continue.
Em Select a provider, selecione AWS.
Insira um nome para o provedor, como “Braze AWS”, e anote o Provider ID.
Em AWS account ID, insira o número de 12 dígitos que segue arn:aws:sts:: no ARN principal da Braze e selecione Continue.
Em Configure provider attributes, mantenha o mapeamento padrão, incluindo google.subject = assertion.arn.
Selecione Save.

Os IDs do pool e do provedor devem ter de 4 a 32 caracteres, usando letras minúsculas, números e hifens.

Restrinja o provedor ao seu principal (opcional)

Para uma defesa em profundidade, adicione uma condição de atributo para que o provedor aceite apenas o principal do seu espaço de trabalho. O Google então rejeita todas as outras identidades na troca de token, antes de verificar qualquer permissão da conta de serviço.

No pool, selecione o provedor e depois selecione Edit.
Em Attribute conditions, selecione Add condition.

Insira a seguinte condição, substituindo BRAZE_PRINCIPAL_ARN pelo valor completo que você copiou na Etapa 1:

 assertion.arn == 'BRAZE_PRINCIPAL_ARN'

Selecione Save.

Essa condição dedica o provedor a um único espaço de trabalho da Braze. Para conectar outro espaço de trabalho, crie um provedor separado ou liste ambos os principais, como em assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].

Etapa 4: crie a conta de serviço

Se você já tem uma conta de serviço para a Braze, como uma da configuração do GCS, pule esta etapa.

Acesse IAM & Admin > Service Accounts e selecione Create service account.
Insira um nome, como “Braze CDI”, e selecione Create and continue.
Pule as etapas opcionais de função do projeto e acesso do usuário e selecione Done. Você concederá acesso aos dados na Etapa 6.

Etapa 5: vincule o principal da Braze à conta de serviço

Conceda ao principal do seu espaço de trabalho permissão para simular a conta de serviço:

Acesse IAM & Admin > Workload Identity Federation e selecione seu pool.
Selecione Grant access e depois selecione Grant access using service account impersonation.
Em Service account, selecione a conta de serviço da Etapa 4.
Em Select principals, selecione Only identities matching the filter.
Em Attribute name, selecione subject. Em Attribute value, cole o ARN principal completo da Braze da Etapa 1.
Selecione Save. Se o Google oferecer o download de um arquivo de configuração de biblioteca de cliente, selecione Dismiss. A Braze não precisa dele.

Isso concede a função Workload Identity User (roles/iam.workloadIdentityUser) na conta de serviço a um principal neste formato:

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

Para confirmar, abra a conta de serviço e selecione a guia Permissions. A função Workload Identity User deve listar esse principal, terminando com seu ARN principal completo da Braze.

Aviso

Não selecione All identities in the pool e não filtre por aws_role. Ambas as opções correspondem a todos os espaços de trabalho da Braze na sua instância da Braze, pois todos compartilham a mesma função AWS. Para mais detalhes, consulte Confie apenas no principal do seu espaço de trabalho.

Conceda essa função apenas na conta de serviço. Uma concessão no nível do projeto permite que o principal simule todas as contas de serviço do projeto.

Alterações no IAM podem levar alguns minutos para entrar em vigor. Se um teste de conexão falhar logo após a concessão de acesso, aguarde alguns minutos e tente novamente.

Etapa 6: conceda à conta de serviço acesso aos seus dados

Conceda à conta de serviço as permissões para a sua fonte:

BigQuery: as funções do BigQuery na Etapa 1.2 de Integrações de data warehouse ou na Etapa 2.1 de Fontes conectadas
Google Cloud Storage: as permissões de bucket e inscrição em Atribuir permissões

Se você usa uma credencial para ambas as fontes, conceda os dois conjuntos de permissões à mesma conta de serviço.

Etapa 7: insira os valores na Braze

Retorne ao formulário de credenciais da Braze e insira os seguintes valores do console do Google Cloud:

Campo na Braze	Onde encontrar
Project number	O cartão Project info no Dashboard do console. Use o número do projeto em vez do ID do projeto.
Workload identity pool ID	O Pool ID da Etapa 3
Provider ID	O Provider ID da Etapa 3
Service account email	O Email da conta de serviço na página Service Accounts

A Braze combina o número do projeto, o ID do pool e o ID do provedor no público, que informa ao Google qual provedor valida a solicitação da Braze. Por padrão, um provedor aceita seu próprio nome de recurso como público. Se você definir públicos permitidos personalizados no seu provedor, inclua o nome de recurso completo do provedor.

Etapa 8: teste a conexão

Quando você testa a conexão na Braze, a Braze também verifica se sua configuração confia apenas no seu espaço de trabalho. Durante o teste, a Braze tenta a mesma troca com um nome de sessão de teste composto inteiramente por zeros, neste formato:

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

Sua configuração deve rejeitar essa identidade, seja na troca de token ou quando ela tentar simular sua conta de serviço. Se ambas as etapas forem bem-sucedidas, o teste falha, porque sua configuração confia em identidades que não são o principal do seu espaço de trabalho. Para corrigir isso, consulte a seção Sua configuração confia em identidades que não são do seu espaço de trabalho.

Se você definiu a condição de atributo opcional, o Google rejeita a identidade de teste na troca de token. Caso contrário, o Google rejeita a identidade de teste quando ela tenta simular sua conta de serviço. De qualquer forma, o teste é aprovado.

Você pode ver essa tentativa rejeitada nos logs de auditoria do Google Cloud cada vez que testar a conexão. Esse comportamento é esperado. A tentativa vem da verificação da Braze e não concede a ninguém acesso aos seus dados.

Não adicione uma condição que rejeite apenas essa sessão de teste. Essa condição faz o teste ser aprovado enquanto sua configuração ainda confia em outros espaços de trabalho da Braze.

Removendo o acesso da Braze

Para impedir que a Braze acesse seus dados, remova a função Workload Identity User do principal da Braze na guia Permissions da conta de serviço ou exclua o provedor.

Configuração com a CLI gcloud

Se você prefere a linha de comando, os comandos a seguir concluem as Etapas 2 a 5. Substitua os valores no primeiro bloco e cole o ARN principal da Braze exatamente como copiado.

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

Solução de problemas

Sua configuração confia em identidades que não são do seu espaço de trabalho

O teste de conexão falha com o seguinte erro:

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.

Isso significa que o Google aceitou a identidade de teste da Braze tanto na troca de token quanto na simulação da conta de serviço, conforme descrito na Etapa 8. Esse erro geralmente acontece quando a conta de serviço concede acesso a todas as identidades no pool ou a identidades filtradas por aws_role.

Para corrigir esse erro:

No console do Google Cloud, abra a conta de serviço e selecione a guia Permissions.
Encontre todos os principais com a função Workload Identity User que começam com principalSet:// e referenciam seu pool. Remova a função de cada um deles.
Certifique-se de que seu principal completo tem a função, conforme a Etapa 5.
Acesse IAM & Admin > IAM e verifique se há concessões de Workload Identity User no nível do projeto para o seu pool. Remova-as.
Teste a conexão novamente.

Como alternativa, restrinja a condição de atributo do provedor ao seu principal completo, conforme descrito em Restrinja o provedor ao seu principal (opcional). O Google então rejeita todas as outras identidades na troca de token. Ainda assim, recomendamos conceder acesso apenas ao seu principal completo.

A Braze não conseguiu confirmar que seu pool confia apenas neste espaço de trabalho

O teste de conexão falha com o seguinte erro:

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.

A verificação da Braze na Etapa 8 não chegou a um resultado. Por exemplo, um erro de rede ou um erro temporário do Google Cloud interrompeu a verificação. Esse erro não significa que sua configuração é muito ampla. Teste a conexão novamente. Se o erro persistir, entre em contato com o suporte da Braze.

Permissão negada ao simular a conta de serviço

O teste de conexão falha com um erro de permissão em iam.serviceAccounts.getAccessToken. Verifique o seguinte:

A guia Permissions da conta de serviço lista a função Workload Identity User para um principal que termina com seu ARN principal completo da Braze, copiado de um formulário de credenciais do BigQuery ou GCS no mesmo espaço de trabalho.
A IAM Service Account Credentials API está ativada.
Você aguardou alguns minutos desde a concessão de acesso.

A troca de token é rejeitada

O teste de conexão falha no Google Security Token Service na troca de token. Verifique o seguinte:

O número do projeto, o ID do pool e o ID do provedor inseridos na Braze correspondem à sua configuração do Google Cloud.
O AWS account ID do provedor corresponde ao ID da conta no ARN principal da Braze.
Se você definiu uma condição de atributo, ela contém seu ARN principal completo, exatamente como copiado.
Se você definiu públicos permitidos personalizados, eles incluem o nome de recurso completo do provedor.
O pool e o provedor estão ativados.

New Stuff!