Ir al contenido

Configurar Google Cloud para Workload Identity Federation

Esta página explica cómo configurar tu proyecto de Google Cloud para que la ingesta de datos en el cloud (CDI) de Braze pueda acceder a BigQuery y Google Cloud Storage (GCS) con Workload Identity Federation (WIF). Para el resto de la configuración de la fuente, consulta Integraciones con almacén de datos, Fuentes conectadas o Integraciones de almacenamiento de archivos.

Con WIF, Braze se autentica en Google Cloud con una identidad de corta duración de su propio entorno AWS y luego suplanta una cuenta de servicio en tu proyecto. Tú configuras tu proyecto para confiar en esa identidad solo para tu espacio de trabajo. No necesitas crear ni compartir una clave de cuenta de servicio.

Configuras WIF una vez por proyecto de Google Cloud. Una credencial WIF sirve tanto para fuentes de BigQuery como de GCS, así que si ya completaste estos pasos para una, concede a la cuenta de servicio existente acceso a los nuevos datos en el Paso 6 y omite el resto.

Requisitos previos

Para completar estos pasos en la consola de Google Cloud, necesitas permiso para crear pools de identidad de carga de trabajo y cuentas de servicio, y para administrar las políticas de Identity and Access Management (IAM) en la cuenta de servicio y tus datos. Por ejemplo, puedes usar los roles Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) y Service Account Admin (roles/iam.serviceAccountAdmin).

Confiar solo en la identidad principal de tu espacio de trabajo

Cada espacio de trabajo de Braze en la misma instancia de Braze presenta el mismo rol de AWS. Solo el nombre de sesión al final del ARN principal, que es tu ID de espacio de trabajo, es único para ti.

El mapeado de atributos predeterminado de Google para proveedores de AWS asigna aws_role al ARN del rol sin el nombre de sesión. Esto significa que conceder acceso a identidades que coincidan con un valor de aws_role, como principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, confía en cada espacio de trabajo de Braze en tu instancia, incluido el tuyo.

Para mantener tus datos limitados a tu espacio de trabajo:

  • Concede acceso solo a las identidades cuyo subject sea tu ARN principal completo de Braze. Este es el principal principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN.
  • No concedas acceso a Todas las identidades en el pool, ni a identidades filtradas por aws_role o account.
  • No escribas una condición de atributo que compruebe solo la cuenta o el rol de AWS.
  • Mantén el mapeado de atributos predeterminado para google.subject, que es assertion.arn.

El ARN principal de Braze difiere para cada espacio de trabajo e instancia de Braze, y Braze usa un rol de AWS separado para fuentes de Google que para otras fuentes como Snowflake. Copia siempre el valor de un formulario de credenciales de BigQuery o GCS en el espacio de trabajo que estés conectando.

Configurar Workload Identity Federation

Paso 1: Copiar el ARN principal de Braze

En Braze, comienza a crear tu fuente de BigQuery o GCS y selecciona Workload Identity Federation como método de autenticación. Copia el valor en el paso 1 del formulario de credenciales, Copy the Braze principal ARN, y mantén el formulario abierto.

Si el campo muestra Unavailable, WIF no está disponible para tu instancia de Braze. Usa una clave de cuenta de servicio en su lugar.

Paso 2: Habilitar las API necesarias

En la consola de Google Cloud, ve a APIs & Services > Library y habilita las siguientes API para tu proyecto:

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

Paso 3: Crear el pool de identidad de carga de trabajo y el proveedor

  1. Ve a IAM & Admin > Workload Identity Federation y luego selecciona Create pool.
  2. Introduce un nombre para el pool, como “Braze CDI”. Anota el Pool ID y luego selecciona Continue.
  3. En Select a provider, selecciona AWS.
  4. Introduce un nombre de proveedor, como “Braze AWS”, y anota el Provider ID.
  5. En AWS account ID, introduce el número de 12 dígitos que sigue a arn:aws:sts:: en el ARN principal de Braze y luego selecciona Continue.
  6. En Configure provider attributes, mantén el mapeado predeterminado, incluyendo google.subject = assertion.arn.
  7. Selecciona Save.

Los ID de pool y proveedor deben tener de 4 a 32 caracteres, usando letras minúsculas, números y guiones.

Restringir el proveedor a tu identidad principal (opcional)

Para una defensa en profundidad, añade una condición de atributo para que el proveedor solo acepte la identidad principal de tu espacio de trabajo. Google entonces rechaza todas las demás identidades en el intercambio de tokens, antes de que Google compruebe cualquier permiso de cuenta de servicio.

  1. En el pool, selecciona el proveedor y luego selecciona Edit.
  2. En Attribute conditions, selecciona Add condition.

  3. Introduce la siguiente condición, reemplazando BRAZE_PRINCIPAL_ARN con el valor completo que copiaste en el Paso 1:

    


     assertion.arn == 'BRAZE_PRINCIPAL_ARN'
  4. Selecciona Save.

Esta condición dedica el proveedor a un solo espacio de trabajo de Braze. Para conectar otro espacio de trabajo, crea un proveedor separado para él, o incluye ambos principales, como en assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].

Paso 4: Crear la cuenta de servicio

Si ya tienes una cuenta de servicio para Braze, como una de la configuración de GCS, omite este paso.

  1. Ve a IAM & Admin > Service Accounts y luego selecciona Create service account.
  2. Introduce un nombre, como “Braze CDI”, y luego selecciona Create and continue.
  3. Omite los pasos opcionales de rol de proyecto y acceso de usuario, y luego selecciona Done. Concederás acceso a los datos en el Paso 6.

Paso 5: Vincular la identidad principal de Braze a la cuenta de servicio

Concede a la identidad principal de tu espacio de trabajo permiso para suplantar la cuenta de servicio:

  1. Ve a IAM & Admin > Workload Identity Federation y luego selecciona tu pool.
  2. Selecciona Grant access y luego selecciona Grant access using service account impersonation.
  3. En Service account, selecciona la cuenta de servicio del Paso 4.
  4. En Select principals, selecciona Only identities matching the filter.
  5. En Attribute name, selecciona subject. En Attribute value, pega el ARN principal completo de Braze del Paso 1.
  6. Selecciona Save. Si Google ofrece descargar un archivo de configuración de biblioteca de cliente, selecciona Dismiss. Braze no lo necesita.

Esto concede el rol Workload Identity User (roles/iam.workloadIdentityUser) en la cuenta de servicio a una identidad principal con esta forma:




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

Para confirmar, abre la cuenta de servicio y selecciona la pestaña Permissions. El rol Workload Identity User debería mostrar esta identidad principal, terminando en tu ARN principal completo de Braze.

Concede este rol solo en la cuenta de servicio. Una concesión a nivel de proyecto permite que la identidad principal suplante cada cuenta de servicio en el proyecto.

Los cambios de IAM pueden tardar unos minutos en surtir efecto. Si una prueba de conexión falla justo después de conceder acceso, espera unos minutos e inténtalo de nuevo.

Paso 6: Conceder a la cuenta de servicio acceso a tus datos

Concede a la cuenta de servicio los permisos para tu fuente:

Si usas una credencial para ambas fuentes, concede ambos conjuntos de permisos a la misma cuenta de servicio.

Paso 7: Introducir los valores en Braze

Vuelve al formulario de credenciales de Braze e introduce los siguientes valores de la consola de Google Cloud:

Campo en Braze Dónde encontrarlo
Project number La tarjeta Project info en el Dashboard de la consola. Usa el número de proyecto numérico en lugar del ID del proyecto.
Workload identity pool ID El Pool ID del Paso 3
Provider ID El Provider ID del Paso 3
Service account email El Email de la cuenta de servicio en la página Service Accounts

Braze combina el número de proyecto, el ID del pool y el ID del proveedor en la audiencia, que indica a Google qué proveedor valida la solicitud de Braze. De forma predeterminada, un proveedor acepta su propio nombre de recurso como audiencia. Si configuras audiencias permitidas personalizadas en tu proveedor, incluye el nombre de recurso completo del proveedor.

Paso 8: Probar la conexión

Cuando pruebas la conexión en Braze, Braze también verifica que tu configuración confíe solo en tu espacio de trabajo. Durante la prueba, Braze intenta el mismo intercambio con un nombre de sesión de prueba de todos ceros, con esta forma:




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

Tu configuración debe rechazar esta identidad, ya sea en el intercambio de tokens o cuando intente suplantar tu cuenta de servicio. Si ambos pasos tienen éxito, la prueba falla, porque tu configuración confía en identidades que no son la identidad principal de tu espacio de trabajo. Para solucionar esto, consulta la sección Tu configuración confía en identidades que no son las de tu espacio de trabajo.

Si configuraste la condición de atributo opcional, Google rechaza la identidad de prueba en el intercambio de tokens. De lo contrario, Google rechaza la identidad de prueba cuando esa identidad intenta suplantar tu cuenta de servicio. En cualquier caso, la prueba se aprueba.

Es posible que veas este intento rechazado en los registros de auditoría de Google Cloud cada vez que pruebes la conexión. Este comportamiento es esperado. El intento proviene de la verificación de Braze y no otorga a nadie acceso a tus datos.

No añadas una condición que rechace solo esta sesión de prueba. Tal condición pasaría la prueba mientras tu configuración sigue confiando en otros espacios de trabajo de Braze.

Eliminar el acceso de Braze

Para evitar que Braze acceda a tus datos, elimina el rol Workload Identity User de la identidad principal de Braze en la pestaña Permissions de la cuenta de servicio, o elimina el proveedor.

Configuración con la CLI de gcloud

Si prefieres la línea de comandos, los siguientes comandos completan los Pasos 2 a 5. Reemplaza los valores del primer bloque y pega el ARN principal de Braze exactamente como lo copiaste.




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

Solución de problemas

Tu configuración confía en identidades que no son las de tu espacio de trabajo

La prueba de conexión falla con el siguiente error:

Tu pool de identidad de carga de trabajo confía en todos los clientes de Braze, no solo en este espacio de trabajo. Braze se autenticó con una identidad de prueba (000000000000000000000000) que no pertenece a ningún espacio de trabajo de Braze, y tu proyecto de Google Cloud la aceptó, por lo que otro cliente de Braze podría leer estos datos. Concede el rol Workload Identity User en tu cuenta de servicio al ARN principal completo de Braze mostrado en la pantalla de credenciales (principal://…/subject/<full ARN>) en lugar de al rol (principalSet://…/attribute.aws_role/…); restringir la condición de atributo del proveedor del pool a esa misma identidad principal también funciona. Luego prueba la conexión de nuevo.

Esto significa que Google aceptó la identidad de prueba de Braze tanto en el intercambio de tokens como en la suplantación de la cuenta de servicio, como se describe en el Paso 8. Este error suele ocurrir cuando la cuenta de servicio concede acceso a todas las identidades del pool, o a identidades filtradas por aws_role.

Para solucionar este error:

  1. En la consola de Google Cloud, abre la cuenta de servicio y selecciona la pestaña Permissions.
  2. Encuentra cada identidad principal con el rol Workload Identity User que comience con principalSet:// y haga referencia a tu pool. Elimina el rol de cada una.
  3. Asegúrate de que tu identidad principal completa tenga el rol, como en el Paso 5.
  4. Ve a IAM & Admin > IAM y comprueba si hay concesiones de Workload Identity User a nivel de proyecto para tu pool. Elimínalas.
  5. Prueba la conexión de nuevo.

Alternativamente, restringe la condición de atributo del proveedor a tu identidad principal completa, como se describe en Restringir el proveedor a tu identidad principal (opcional). Google entonces rechaza todas las demás identidades en el intercambio de tokens. Aun así, recomendamos conceder acceso solo a tu identidad principal completa.

Braze no pudo confirmar que tu pool confía solo en este espacio de trabajo

La prueba de conexión falla con el siguiente error:

Braze no pudo confirmar que tu pool de identidad de carga de trabajo confía solo en este espacio de trabajo. La verificación necesita que Google rechace explícitamente una identidad que no sea la tuya, y este intento falló por otro motivo. Inténtalo de nuevo; si sigue ocurriendo, contacta con soporte.

La verificación de Braze en el Paso 8 no arrojó un resultado. Por ejemplo, un error de red o un error temporal de Google Cloud interrumpieron la verificación. Este error no significa que tu configuración sea demasiado amplia. Prueba la conexión de nuevo. Si el error persiste, contacta con soporte de Braze.

Permiso denegado cuando Braze suplanta la cuenta de servicio

La prueba de conexión falla con un error de permiso en iam.serviceAccounts.getAccessToken. Comprueba lo siguiente:

  • La pestaña Permissions de la cuenta de servicio muestra el rol Workload Identity User para una identidad principal que termina en tu ARN principal completo de Braze, copiado de un formulario de credenciales de BigQuery o GCS en el mismo espacio de trabajo.
  • La IAM Service Account Credentials API está habilitada.
  • Has esperado unos minutos desde que concediste el acceso.

El intercambio de tokens es rechazado

La prueba de conexión falla en el intercambio de tokens de Google Security Token Service. Comprueba lo siguiente:

  • El número de proyecto, el ID del pool y el ID del proveedor que introdujiste en Braze coinciden con tu configuración de Google Cloud.
  • El ID de cuenta de AWS del proveedor coincide con el ID de cuenta en el ARN principal de Braze.
  • Si configuraste una condición de atributo, contiene tu ARN principal completo, exactamente como lo copiaste.
  • Si configuraste audiencias permitidas personalizadas, incluyen el nombre de recurso completo del proveedor.
  • El pool y el proveedor están habilitados.

Documentación de la plataforma de interacción con el cliente de Braze.

Recursos
Legal
Empresa
© 2026 Braze, Inc. Todos los derechos reservados.
Verificación del estado de Braze
New Stuff!