이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

Workload Identity Federation을 위한 Google Cloud 구성

이 페이지에서는 Braze 클라우드 데이터 수집(CDI)이 Workload Identity Federation(WIF)을 통해 BigQuery와 Google Cloud Storage(GCS)에 액세스할 수 있도록 Google Cloud 프로젝트를 구성하는 방법을 다룹니다. 나머지 소스 설정에 대해서는 데이터 웨어하우스 통합, 연결된 소스 또는 파일 스토리지 통합을 참조하세요.

WIF를 사용하면 Braze가 자체 AWS 환경에서 단기 ID로 Google Cloud에 인증한 다음, 프로젝트 내 서비스 계정을 가장합니다. 해당 ID를 워크스페이스에 대해서만 신뢰하도록 프로젝트를 구성합니다. 서비스 계정 키를 생성하거나 공유할 필요가 없습니다.

WIF는 Google Cloud 프로젝트당 한 번만 설정합니다. 하나의 WIF 자격 증명으로 BigQuery와 GCS 소스를 모두 지원하므로, 이미 이 단계를 완료했다면 6단계에서 기존 서비스 계정에 새 데이터에 대한 액세스를 부여하고 나머지 단계는 건너뛰세요.

사전 요구 사항

Google Cloud 콘솔에서 이 단계를 완료하려면 Workload Identity 풀 및 서비스 계정을 생성하고, 서비스 계정과 데이터에 대한 IAM(Identity and Access Management) 정책을 관리할 수 있는 권한이 필요합니다. 예를 들어, Workload Identity Pool Admin(roles/iam.workloadIdentityPoolAdmin) 및 Service Account Admin(roles/iam.serviceAccountAdmin) 역할을 사용할 수 있습니다.

워크스페이스의 주체만 신뢰하기

경고

자격 증명 양식에 있는 전체 Braze 주체 Amazon Resource Name(ARN)에 대해 액세스를 부여하세요. Braze AWS 역할이나 AWS 계정에 대해 액세스를 부여하지 마세요. 역할 수준 또는 계정 수준으로 부여하면 다른 Braze 고객이 귀하의 데이터를 읽을 수 있습니다.

동일한 Braze 인스턴스에 있는 모든 Braze 워크스페이스는 동일한 AWS 역할을 사용합니다. 주체 ARN 끝의 세션 이름(워크스페이스 ID)만이 고유합니다.

Google의 AWS 공급자에 대한 기본 속성 매핑은 aws_role을 세션 이름 없이 역할 ARN으로 설정합니다. 따라서 aws_role 값과 일치하는 ID에 대해 액세스를 부여하면(예: principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN), 귀하의 워크스페이스를 포함한 인스턴스의 모든 Braze 워크스페이스를 신뢰하게 됩니다.

데이터를 워크스페이스 범위로 유지하려면:

subject가 전체 Braze 주체 ARN인 ID에만 액세스를 부여하세요. 이것은 principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN 주체입니다.
풀의 모든 ID에 대해 액세스를 부여하거나, aws_role 또는 account로 필터링된 ID에 대해 액세스를 부여하지 마세요.
AWS 계정이나 역할만 확인하는 속성 조건을 작성하지 마세요.
google.subject의 기본 속성 매핑(assertion.arn)을 유지하세요.

Braze 주체 ARN은 워크스페이스와 Braze 인스턴스마다 다르며, Braze는 Snowflake 등 다른 소스와 다른 AWS 역할을 Google 소스에 사용합니다. 항상 연결하려는 워크스페이스의 BigQuery 또는 GCS 자격 증명 양식에서 값을 복사하세요.

Workload Identity Federation 설정

1단계: Braze 주체 ARN 복사

Braze에서 BigQuery 또는 GCS 소스 생성을 시작하고 인증 방법으로 Workload Identity Federation을 선택합니다. 자격 증명 양식의 1단계 Braze 주체 ARN 복사에서 값을 복사하고 양식을 열어둡니다.

필드에 사용 불가가 표시되면 해당 Braze 인스턴스에서 WIF를 사용할 수 없습니다. 대신 서비스 계정 키를 사용하세요.

2단계: 필수 API 활성화

Google Cloud 콘솔에서 APIs & Services > Library로 이동하여 프로젝트에 다음 API를 활성화합니다.

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

3단계: Workload Identity 풀 및 공급자 생성

IAM & Admin > Workload Identity Federation으로 이동한 다음 Create pool을 선택합니다.
풀 이름을 입력합니다(예: “Braze CDI”). Pool ID를 확인한 다음 Continue를 선택합니다.
Select a provider에서 AWS를 선택합니다.
공급자 이름을 입력합니다(예: “Braze AWS”). Provider ID를 확인합니다.
AWS account ID에 Braze 주체 ARN의 arn:aws:sts:: 뒤에 오는 12자리 숫자를 입력한 다음 Continue를 선택합니다.
Configure provider attributes에서 google.subject = assertion.arn을 포함한 기본 매핑을 유지합니다.
Save를 선택합니다.

풀 및 공급자 ID는 소문자, 숫자, 하이픈을 사용하여 4~32자여야 합니다.

공급자를 주체로 제한하기(선택 사항)

심층 방어를 위해 속성 조건을 추가하여 공급자가 워크스페이스의 주체만 수락하도록 합니다. Google은 서비스 계정 권한을 확인하기 전, 토큰 교환 시 다른 모든 ID를 거부합니다.

풀에서 공급자를 선택한 다음 Edit를 선택합니다.
Attribute conditions에서 Add condition을 선택합니다.

다음 조건을 입력합니다. BRAZE_PRINCIPAL_ARN을 1단계에서 복사한 전체 값으로 교체합니다.

 assertion.arn == 'BRAZE_PRINCIPAL_ARN'

Save를 선택합니다.

이 조건은 공급자를 하나의 Braze 워크스페이스 전용으로 할당합니다. 다른 워크스페이스를 연결하려면 별도의 공급자를 생성하거나, assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN']과 같이 두 주체를 모두 나열하세요.

4단계: 서비스 계정 생성

GCS 설정 등에서 이미 Braze용 서비스 계정이 있다면 이 단계를 건너뛰세요.

IAM & Admin > Service Accounts로 이동한 다음 Create service account를 선택합니다.
이름을 입력합니다(예: “Braze CDI”). Create and continue를 선택합니다.
선택 사항인 프로젝트 역할 및 사용자 액세스 단계를 건너뛰고 Done을 선택합니다. 데이터 액세스는 6단계에서 부여합니다.

5단계: Braze 주체를 서비스 계정에 바인딩

워크스페이스의 주체에 서비스 계정 가장 권한을 부여합니다.

IAM & Admin > Workload Identity Federation으로 이동한 다음 풀을 선택합니다.
Grant access를 선택한 다음 Grant access using service account impersonation을 선택합니다.
Service account에서 4단계의 서비스 계정을 선택합니다.
Select principals에서 Only identities matching the filter를 선택합니다.
Attribute name에서 subject를 선택합니다. Attribute value에 1단계의 전체 Braze 주체 ARN을 붙여넣습니다.
Save를 선택합니다. Google에서 클라이언트 라이브러리 구성 파일 다운로드를 제안하면 Dismiss를 선택합니다. Braze에는 필요하지 않습니다.

이렇게 하면 서비스 계정에 대해 다음 형식의 주체에 Workload Identity User 역할(roles/iam.workloadIdentityUser)이 부여됩니다.

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

확인하려면 서비스 계정을 열고 Permissions 탭을 선택합니다. Workload Identity User 역할에 전체 Braze 주체 ARN으로 끝나는 주체가 나열되어야 합니다.

경고

All identities in the pool을 선택하거나 aws_role로 필터링하지 마세요. 모든 Braze 워크스페이스가 동일한 AWS 역할을 공유하므로 인스턴스의 모든 Braze 워크스페이스와 일치합니다. 자세한 내용은 워크스페이스의 주체만 신뢰하기를 참조하세요.

이 역할은 서비스 계정에서만 부여하세요. 프로젝트 수준으로 부여하면 주체가 프로젝트 내 모든 서비스 계정을 가장할 수 있습니다.

IAM 변경 사항이 적용되기까지 몇 분이 걸릴 수 있습니다. 액세스 부여 직후 연결 테스트가 실패하면 몇 분 기다린 후 다시 시도하세요.

6단계: 서비스 계정에 데이터 액세스 부여

소스에 따라 서비스 계정에 권한을 부여합니다.

BigQuery: 데이터 웨어하우스 통합의 1.2단계 또는 연결된 소스의 2.1단계에 있는 BigQuery 역할
Google Cloud Storage: 권한 할당의 버킷 및 구독 권한

두 소스에 하나의 자격 증명을 사용하는 경우 동일한 서비스 계정에 두 세트의 권한을 모두 부여하세요.

7단계: Braze에 값 입력

Braze 자격 증명 양식으로 돌아가 Google Cloud 콘솔의 다음 값을 입력합니다.

Braze 필드	확인 위치
프로젝트 번호	콘솔 대시보드의 Project info 카드. 프로젝트 ID가 아닌 숫자로 된 프로젝트 번호를 사용합니다.
Workload Identity 풀 ID	3단계의 Pool ID
공급자 ID	3단계의 Provider ID
서비스 계정 이메일	Service Accounts 페이지의 서비스 계정 Email

Braze는 프로젝트 번호, 풀 ID, 공급자 ID를 결합하여 오디언스를 구성하며, 이를 통해 Google에 Braze의 요청을 검증할 공급자를 알려줍니다. 기본적으로 공급자는 자체 리소스 이름을 오디언스로 수락합니다. 공급자에 커스텀 허용 오디언스를 설정한 경우 공급자의 전체 리소스 이름을 포함하세요.

8단계: 연결 테스트

Braze에서 연결을 테스트하면 구성이 워크스페이스만 신뢰하는지도 확인합니다. 테스트 중에 Braze는 다음 형식의 모두 0인 테스트 세션 이름으로 동일한 교환을 시도합니다.

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

이 ID는 토큰 교환 시 또는 서비스 계정 가장 시도 시 거부되어야 합니다. 두 단계 모두 성공하면 구성이 워크스페이스의 주체 외의 ID도 신뢰하고 있으므로 테스트가 실패합니다. 이를 해결하려면 구성이 워크스페이스 외의 ID를 신뢰하는 경우 섹션을 참조하세요.

선택적 속성 조건을 설정한 경우 Google은 토큰 교환 시 테스트 ID를 거부합니다. 그렇지 않으면 해당 ID가 서비스 계정 가장을 시도할 때 Google이 거부합니다. 어느 경우든 테스트는 통과합니다.

연결을 테스트할 때마다 Google Cloud 감사 로그에 이 거부된 시도가 나타날 수 있습니다. 이는 예상된 동작입니다. 이 시도는 Braze 점검에서 발생하며 누구에게도 데이터 액세스를 제공하지 않습니다.

이 테스트 세션만 거부하는 조건을 추가하지 마세요. 그러한 조건은 테스트를 통과시키지만 구성이 여전히 다른 Braze 워크스페이스를 신뢰하게 됩니다.

Braze 액세스 제거

Braze가 데이터에 액세스하지 못하게 하려면 서비스 계정의 Permissions 탭에서 Braze 주체의 Workload Identity User 역할을 제거하거나 공급자를 삭제하세요.

gcloud CLI로 설정

명령줄을 선호하는 경우 다음 명령으로 2~5단계를 완료할 수 있습니다. 첫 번째 블록의 값을 교체하고 Braze 주체 ARN을 복사한 그대로 붙여넣으세요.

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

문제 해결

구성이 워크스페이스 외의 ID를 신뢰하는 경우

연결 테스트가 다음 오류와 함께 실패합니다.

Workload Identity 풀이 이 워크스페이스뿐만 아니라 모든 Braze 고객을 신뢰합니다. Braze가 어떤 Braze 워크스페이스에도 속하지 않는 테스트 ID(000000000000000000000000)로 인증을 시도했으며 Google Cloud 프로젝트가 이를 수락했으므로, 다른 Braze 고객이 이 데이터를 읽을 수 있습니다. 자격 증명 화면에 표시된 전체 Braze 주체(principal://…/subject/<full ARN>)에 서비스 계정의 Workload Identity User 역할을 부여하세요. 역할(principalSet://…/attribute.aws_role/…)에 부여하지 마세요. 풀 공급자의 속성 조건을 동일한 주체로 제한하는 것도 가능합니다. 그런 다음 연결을 다시 테스트하세요.

이는 8단계에 설명된 대로 Google이 토큰 교환과 서비스 계정 가장 모두에서 Braze 테스트 ID를 수락했음을 의미합니다. 이 오류는 일반적으로 서비스 계정이 풀의 모든 ID 또는 aws_role로 필터링된 ID에 액세스를 부여할 때 발생합니다.

이 오류를 해결하려면:

Google Cloud 콘솔에서 서비스 계정을 열고 Permissions 탭을 선택합니다.
Workload Identity User 역할이 있으면서 principalSet://로 시작하고 풀을 참조하는 모든 주체를 찾습니다. 각 주체에서 역할을 제거합니다.
5단계와 같이 전체 주체에 역할이 있는지 확인합니다.
IAM & Admin > IAM으로 이동하여 풀에 대한 프로젝트 수준 Workload Identity User 부여를 확인합니다. 이를 제거합니다.
연결을 다시 테스트합니다.

또는 공급자를 주체로 제한하기(선택 사항)에 설명된 대로 공급자의 속성 조건을 전체 주체로 제한합니다. 그러면 Google이 토큰 교환 시 다른 모든 ID를 거부합니다. 그래도 전체 주체에만 액세스를 부여하는 것을 권장합니다.

Braze가 풀이 이 워크스페이스만 신뢰하는지 확인할 수 없는 경우

연결 테스트가 다음 오류와 함께 실패합니다.

Braze가 Workload Identity 풀이 이 워크스페이스만 신뢰하는지 확인할 수 없습니다. 이 점검은 Google이 귀하의 것이 아닌 ID를 명시적으로 거부해야 하는데, 이 시도가 다른 이유로 실패했습니다. 다시 시도하세요. 오류가 계속 발생하면 지원팀에 문의하세요.

8단계의 Braze 점검이 결과에 도달하지 못했습니다. 예를 들어, 네트워크 오류 또는 일시적인 Google Cloud 오류로 점검이 중단되었을 수 있습니다. 이 오류가 구성이 너무 광범위하다는 것을 의미하지는 않습니다. 연결을 다시 테스트하세요. 오류가 계속 발생하면 Braze 지원팀에 문의하세요.

Braze가 서비스 계정을 가장할 때 권한 거부

연결 테스트가 iam.serviceAccounts.getAccessToken에 대한 권한 오류로 실패합니다. 다음을 확인하세요.

서비스 계정의 Permissions 탭에 동일한 워크스페이스의 BigQuery 또는 GCS 자격 증명 양식에서 복사한 전체 Braze 주체 ARN으로 끝나는 주체의 Workload Identity User 역할이 나열되어 있는지 확인합니다.
IAM Service Account Credentials API가 활성화되어 있는지 확인합니다.
액세스 부여 후 몇 분이 경과했는지 확인합니다.

토큰 교환 거부

연결 테스트가 Google Security Token Service 토큰 교환에서 실패합니다. 다음을 확인하세요.

Braze에 입력한 프로젝트 번호, 풀 ID, 공급자 ID가 Google Cloud 구성과 일치하는지 확인합니다.
공급자의 AWS 계정 ID가 Braze 주체 ARN의 계정 ID와 일치하는지 확인합니다.
속성 조건을 설정한 경우 복사한 그대로의 전체 주체 ARN이 포함되어 있는지 확인합니다.
커스텀 허용 오디언스를 설정한 경우 공급자의 전체 리소스 이름이 포함되어 있는지 확인합니다.
풀과 공급자가 활성화되어 있는지 확인합니다.

New Stuff!