Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

직원 ID 제휴 (BYOID) 구성

이 가이드에서는 직원 ID 제휴 및 워크로드 아이덴티티 제휴를 사용하여 다자간 계산 API에 Bring Your Own Identity (BYOID)를 구성하는 방법을 설명합니다. ID 제휴를 사용하면 인간 사용자와 자동화된 서명자 워크로드가 조직의 외부 ID 공급업체(IdP)(예: Okta, Microsoft Entra ID, Ping Identity)를 사용하여 다자간 계산에 인증할 수 있습니다. Google 계정을 만들거나 장기간 사용 가능한 서비스 계정 키를 관리할 필요가 없습니다.

개요

ID 제휴는 다음 레이어에서 다자간 계산 심층 방어 보안 모델과 통합됩니다.

에지 Identity and Access Management (IAM) 승인: 호출자는 외부 OpenID Connect (OIDC) 또는 SAML 2.0 IdP의 사용자 인증 정보를 Google Cloud 보안 토큰 서비스 (보안 토큰 서비스)와 교환하여 단기 제휴 액세스 토큰을 가져옵니다. Google Cloud API 게이트웨이는 요청을 다자간 컴퓨팅 인스턴스로 전달하기 전에 제휴 주 구성원 URI에 대해 IAM 역할 바인딩을 평가하고 Cloud 감사 로그의 제휴 ID (principalSubject)를 전파합니다.
직무 분리 및 암호화 승인: IAM 역할은 관리 프로비저닝 (roles/mpc.admin), 운영 참여 (roles/mpc.editor), 읽기 전용 감독 (roles/mpc.viewer)을 분리합니다. 인스턴스 내에서 관리자, 정책 작성자, 서명자에게도 인스턴스가 사용자를 대신하여 작동하는 메서드를 확인하는 역할 (ADMIN, POLICY_AUTHOR 또는 SIGNER)을 가진 사용자가 필요하며, 승인은 해당 사용자에 등록된 승인 키로 서명되어야 합니다. 자세한 내용은 요청 승인 방법을 참조하세요.

호출자 유형에 따라 두 가지 ID 제휴 메커니즘을 사용할 수 있습니다.

직원 ID 제휴 (locations/global/workforcePools/...): 기업 IdP에 매핑된 조직 수준 직원 풀을 사용하여 사람 사용자 (관리자, 정책 작성자, 서명자, 규정 준수)를 인증합니다. 이 가이드에서는 직원 ID 제휴를 처음부터 끝까지 구성하는 방법을 설명합니다.
워크로드 아이덴티티 제휴 (projects/.../locations/global/workloadIdentityPools/...): 프로젝트 수준 워크로드 아이덴티티 풀을 사용하여 자동화된 워크로드 (예: AWS, Azure 또는 Kubernetes에서 실행되는 헤드리스 공동 서명자 데몬)를 인증합니다.

IAM 역할이 다자간 컴퓨팅 가상 사용자에 매핑되는 방식에 대한 자세한 내용은 보안 및 승인을 참조하세요.

시작하기 전에

시작하기 전에 다음 사항을 확인하세요.

다자간 계산에 온보딩된 Google Cloud 조직 및 소비자 프로젝트
gcloud CLI 및 jq가 설치되어 있고 다음 역할을 보유한 관리 계정으로 gcloud가 인증되었습니다.
- Google Cloud 조직의 직원 풀 관리자 (roles/iam.workforcePoolAdmin)(1단계에서 새 직원 풀을 만드는 경우)
- 소비자 프로젝트의 프로젝트 IAM 관리자 (roles/resourcemanager.projectIamAdmin) 및 서비스 사용량 관리자 (roles/serviceusage.serviceUsageAdmin)

소비자 프로젝트에서 사용 설정된 필수 API:

gcloud services enable mpc.googleapis.com iam.googleapis.com sts.googleapis.com \
  --project="my-project"

기업 IdP에 구성된 외부 OIDC 또는 SAML 2.0 애플리케이션 gcloud CLI에서 대화형 브라우저 로그인을 사용하려면 IdP 애플리케이션에서 Google Cloud 리디렉션 URI를 구성합니다(Okta 및 Microsoft Entra ID 설정 가이드 참조).

설정

다음 변수를 업데이트하여 이 가이드 전체의 명령어를 채웁니다.

필수 설정 매개변수

Google Cloud 환경 및 외부 IdP 구성에 맞게 이러한 매개변수를 맞춤설정합니다.

매개변수	값	설명
조직 ID	`123456789012`	숫자 Google Cloud 조직 ID입니다.
프로젝트 ID	`my-project`	다자간 컴퓨팅 인스턴스에 등록된 소비자 프로젝트 ID입니다.
도메인 ID	`67317436-0f29-ba9e-9146-d11c0bd8df9b`	다자간 컴퓨팅 인스턴스에 할당된 고유 도메인 ID입니다.
인스턴스 경로 ID	`mpc-unit-bob-123`	다자간 컴퓨팅 인스턴스에 할당된 인스턴스 경로 ID입니다.
위치	`us-central1`	배포 위치 (`us-central1`). 자세한 내용은 다자간 계산 위치를 참조하세요.
직원 풀 ID	`mpc-workforce-pool`	조직 수준 직원 ID 풀 ID입니다.
제공업체 ID	`mpc-oidc-provider`	직원 ID 풀 공급업체 ID입니다.
IdP 발급기관 URI	`https://idp.example.com`	외부 OIDC IdP 발급기관 URI입니다.
IdP 클라이언트 ID	`mpc-client`	외부 IdP에 구성된 OAuth 2.0 클라이언트 ID입니다.

1단계: 직원 ID 풀 및 공급업체 구성

직원 ID 풀 (locations/global/workforcePools/mpc-workforce-pool)은 엔터프라이즈 IdP 테넌트에 매핑되는 조직 수준 리소스입니다. 프로젝트 또는 역할마다 별도의 직원 풀을 만들 필요가 없습니다.

Google Cloud 조직에서 직원 ID 풀을 만듭니다.

gcloud iam workforce-pools create "mpc-workforce-pool" \
  --organization="123456789012" \
  --location="global" \
  --display-name="MPC Workforce Pool"

외부 IdP를 신뢰하고 주체 및 그룹 클레임을 매핑하는 OIDC 직원 풀 공급업체를 만듭니다.
```
gcloud iam workforce-pools providers create-oidc "mpc-oidc-provider" \
  --workforce-pool="mpc-workforce-pool" \
  --location="global" \
  --display-name="MPC Enterprise OIDC Provider" \
  --issuer-uri="https://idp.example.com" \
  --client-id="mpc-client" \
  --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups" \
  --web-sso-response-type="id-token" \
  --web-sso-assertion-claims-behavior="only-id-token-claims"
```
참고: 기본적으로 Security Token Service는 IdP의 /.well-known/openid-configuration 엔드포인트에서 공개 서명 키를 검색하고 순환합니다. 공개적으로 연결할 수 없는 오프라인 또는 합성 OIDC 발급기관으로 테스트하는 경우 --jwk-json-path="<var>PATH_TO_JWK_FILE</var>"를 전달하고 <var>PATH_TO_JWK_FILE</var>를 발급기관의 공개 JSON 웹 키 세트 (JWKS) 파일의 로컬 경로로 바꿉니다. SAML 2.0 제공업체의 경우 gcloud iam workforce-pools providers create-saml를 --idp-metadata-path와 함께 사용합니다.

2단계: 제휴 주 구성원에게 IAM 역할 부여

MPC API를 호출하려면 제휴 주 구성원에게 소비자 프로젝트 (my-project)에 대한 두 가지 유형의 IAM 역할 바인딩이 필요합니다.

서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer): 제휴 ID가 API 할당량 및 결제를 소비자 프로젝트에 할당할 수 있도록 승인합니다.
특정 다자간 계산 작업을 승인하는 다자간 계산 역할 (roles/mpc.admin, roles/mpc.editor 또는 roles/mpc.viewer)

프로덕션에서는 직원 풀 내의 고유한 IdP 그룹에 IAM 역할을 바인딩합니다.

# 1. Allow members of the workforce pool to consume APIs through the consumer project
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/serviceusage.serviceUsageConsumer" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/*"

# 2. Grant MPC Admin to the enterprise administrators group
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.admin" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-admins"

# 3. Grant MPC Editor to Policy Authors and Signers groups
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.editor" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-policy-authors"

gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.editor" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-signers"

# 4. Grant MPC Viewer to the Compliance group
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.viewer" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-auditors"

자동 서명자 워크로드 (워크로드 아이덴티티 제휴)

Google Cloud 외부(예: AWS, Azure 또는 Kubernetes)에서 자동화된 공동 서명자 데몬을 실행하는 경우 프로젝트 범위의 워크로드 아이덴티티 풀 및 공급업체를 구성합니다. 워크로드 주 구성원에 roles/serviceusage.serviceUsageConsumer 및 roles/mpc.editor을 부여하고 (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>, <var>PROJECT_NUMBER</var>, <var>WORKLOAD_POOL_ID</var>, <var>SIGNER_NODE_SUBJECT</var>를 프로젝트 번호, 워크로드 풀 ID, 워크로드 sub 클레임으로 대체) gcloud iam workload-identity-pools create-cred-config를 사용하여 애플리케이션 기본 사용자 인증 정보 파일을 생성합니다.

제휴 ID를 v1beta 사용자로 추가

v1beta API에서 이 단계의 IAM 역할을 사용하면 제휴 ID가 인스턴스를 호출할 수 있습니다. 인스턴스 내에서 관리자, 정책 작성자 또는 서명자로 활동하려면 ID에 사용자도 필요합니다. 인스턴스는 호출자의 주 구성원을 각 사용자의 principal 필드와 일치시켜 호출자를 식별합니다.

직원 ID 제휴 ID의 경우 principal를 ID의 주체 주 구성원 식별자로 설정합니다.

principal://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/subject/SUBJECT_ID

SUBJECT_ID를 제공업체가 google.subject에 매핑하는 값으로 바꿉니다. 1단계의 속성 매핑을 사용하면 사용자 ID 토큰의 sub 클레임입니다.

principal를 설정할 때는 다음 사항에 유의하세요.

principalSet:// 식별자가 아닌 principal:// 식별자를 사용합니다. 사용자는 한 사람입니다. principalSet://.../group/mpc-signers와 같은 그룹 및 풀 식별자는 IAM 역할 바인딩에서 작동하지만 호출자와 일치하지 않으므로 이를 사용하여 만든 사용자는 인스턴스에서 작동할 수 없습니다.
제목과 정확히 일치 인스턴스는 직원 및 워크로드 주체를 대소문자를 구분하여 비교하므로 IdP에서 발급한 주체를 복사합니다. Google 계정 이메일(예: alice@example.com)은 대소문자를 구분하지 않고 비교됩니다.
principal은 나중에 변경할 수 없습니다. 사용자 ID를 변경하려면 사용자를 사용 중지하고 새 사용자를 만드세요.

3단계: 인증 및 제휴 액세스 토큰 가져오기

MPC API는 IdP에서 직접 OIDC 토큰 또는 SAML 어설션을 허용하지 않습니다. 다자간 컴퓨팅 인스턴스 엔드포인트 (*.mpc.goog)를 호출하기 전에 보안 토큰 서비스를 사용하여 IdP 사용자 인증 정보를 제휴 Google Cloud 액세스 토큰으로 교환합니다.

애플리케이션 기본 사용자 인증 정보 (ADC) 및 gcloud CLI를 사용하여 자동으로 또는 Security Token Service API를 사용하여 프로그래매틱 방식으로 제휴 액세스 토큰을 가져오고 관리할 수 있습니다.

애플리케이션 기본 사용자 인증 정보 및 gcloud CLI

프로덕션 클라이언트 애플리케이션 및 대화형 CLI 세션에서 구성 파일을 사용하여 Google Cloud SDK 및 Cloud 클라이언트 라이브러리가 백그라운드 Security Token Service 토큰 교환, 캐싱, 새로고침을 자동으로 처리하도록 합니다.

옵션 A: 대화형 브라우저 로그인

로그인 구성 파일을 생성하고 회사 IdP를 사용하여 gcloud CLI와 애플리케이션 기본 사용자 인증 정보 (ADC)를 모두 인증합니다.

gcloud iam workforce-pools create-login-config \
  "locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --activate \
  --output-file="login-config.json"

gcloud config set billing/quota_project "my-project"
gcloud auth login --login-config="login-config.json"
gcloud auth application-default login --login-config="login-config.json"

옵션 B: 사용자 인증 정보 구성 파일 (ADC)을 사용한 비대화형 로그인

외부 프로세스가 토큰이 만료되기 전에 로컬 파일 (예: /var/run/secrets/tokens/oidc-token)에서 서명된 OIDC 토큰을 제공하고 새로고침하는 경우 외부 사용자 인증 정보 구성 파일을 생성합니다.

gcloud iam workforce-pools create-cred-config \
  "locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
  --credential-source-file="/var/run/secrets/tokens/oidc-token" \
  --workforce-pool-user-project="my-project" \
  --output-file="credential-config.json"

export GOOGLE_APPLICATION_CREDENTIALS="$(pwd)/credential-config.json"

curl 요청의 액세스 토큰을 내보냅니다.

옵션 A 또는 옵션 B를 완료한 후 ADC에서 ACCESS_TOKEN로 제휴 액세스 토큰을 내보냅니다.

export ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"

직접 REST STS 토큰 교환

Google Cloud SDK 없이 커스텀 클라이언트를 통합하는 경우 서명된 OIDC ID 토큰 (<var>IDP_ID_TOKEN</var>)을 Security Token Service와 직접 교환합니다. Google Cloud 에서 토큰을 소비자 프로젝트에 할당하도록 options 필드에 userProject를 포함합니다.

# Set IDP_ID_TOKEN to the signed OIDC JWT assertion from your external IdP
# export IDP_ID_TOKEN="eyJhbGciOiJSUzI1NiIs..."

STS_RESPONSE=$(curl -sS -X POST "https://sts.googleapis.com/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
  --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  --data-urlencode "subject_token=${IDP_ID_TOKEN}" \
  --data-urlencode 'options={"userProject":"my-project"}')

export ACCESS_TOKEN=$(echo "${STS_RESPONSE}" | jq -er '.access_token') || echo "${STS_RESPONSE}" | jq .

4단계: 제휴 API 액세스 확인

다자간 컴퓨팅 인스턴스의 사용자를 나열하여 제휴 사용자 인증 정보, userProject 기여 분석, IAM 역할 바인딩이 작동하는지 확인합니다. mpc.googleapis.com/users.list는 roles/mpc.viewer, roles/mpc.editor, roles/mpc.admin에 포함되어 있으므로 승인된 제휴 가상 사용자는 이 검사를 실행할 수 있습니다.

curl -sS -X GET \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: my-project" \
  "https://67317436-0f29-ba9e-9146-d11c0bd8df9b.us-central1.mpc.goog/v1beta/projects/my-project/locations/us-central1/instances/mpc-unit-bob-123/users" | jq .

200 OK JSON 응답 (새 인스턴스의 {} 또는 users 목록)은 제휴 ID가 인증되고 다자간 컴퓨팅 인스턴스를 호출할 수 있는 권한이 있음을 확인합니다.

이 검사에서는 IAM만 사용합니다. 인스턴스가 내 ID를 사용자로 인식하는지 확인하려면 반환된 사용자 중 하나의 principal 필드에 내 principal:// 식별자가 있는지 확인합니다. 자세한 내용은 제휴 ID를 v1beta 사용자로 추가를 참조하세요.

문제 해결

제휴 사용자 인증 정보로 다자간 계산을 호출할 때 인증 또는 권한 오류가 발생하면 다음 요구사항을 확인하세요.

사용자 프로젝트 기여 분석 (`401 UNAUTHENTICATED: Unable to determine client project number`)

원인: 조직 수준 직원 풀 사용자 인증 정보는 토큰 교환 중 또는 요청 시 사용자 프로젝트가 지정되지 않는 한 기본적으로 단일 Google Cloud 프로젝트에 바인딩되지 않습니다.
해결 방법: Security Token Service 토큰 교환 요청 본문에 options: {"userProject": "<var>PROJECT_ID</var>"}(또는 gcloud iam workforce-pools create-cred-config의 --workforce-pool-user-project)를 포함하고 MPC API 호출에 X-Goog-User-Project: <var>PROJECT_ID</var> 헤더를 포함합니다.

서비스 사용 권한 누락 (`403 PERMISSION_DENIED`)

원인: 제휴 주 구성원 또는 그룹에 API 사용량을 userProject 또는 X-Goog-User-Project에 지정된 소비자 프로젝트에 기여할 권한이 없습니다.
해결 방법: 소비자 프로젝트에서 principal:// 또는 principalSet:// 구성원에게 roles/serviceusage.serviceUsageConsumer을 부여합니다(2단계 참조).

소비자 프로젝트 불일치 (`403 PERMISSION_DENIED: Project is not allowed to call the API through this host`)

원인: 각 전용 다자간 계산 컴퓨팅 인스턴스 엔드포인트는 해당 인스턴스에 구성된 소비자 프로젝트의 요청만 허용합니다.
해결 방법: 요청 URL 경로와 userProject / X-Goog-User-Project 헤더의 <var>PROJECT_ID</var>가 다자간 연산 컴퓨팅 인스턴스에 프로비저닝된 소비자 프로젝트와 일치하는지 확인합니다.

잘못된 사용자 인증 정보 (`401 UNAUTHENTICATED: Request credential is invalid`)

원인: 서드 파티 OIDC 토큰 또는 SAML 어설션이 먼저 보안 토큰 서비스를 사용하여 교환되지 않고 다자간 계산 엔드포인트로 직접 전송되었습니다.
해결 방법: https://sts.googleapis.com/v1/token를 통해 IdP 사용자 인증 정보를 교환하거나 애플리케이션 기본 사용자 인증 정보를 사용하고 결과 Google Cloud 액세스 토큰을 Authorization: Bearer 헤더에 전달합니다.

도메인 제한 공유 정책이 역할 바인딩을 차단함 (`400 FAILED_PRECONDITION`)

원인: Google Cloud 조직에서 프로젝트에 IAM 역할을 부여할 수 있는 주 구성원 도메인을 제한하는 constraints/iam.allowedPolicyMemberDomains 조직 정책을 시행합니다.
해결 방법: 조직 정책 관리자에게 소비자 프로젝트 또는 조직의 허용된 정책 구성원 도메인에 직원 풀 주 구성원 집합을 추가해 달라고 요청하거나 constraints/iam.allowedPolicyMemberDomains에서 직원 풀을 허용하는 프로젝트에서 테스트합니다.

다음 단계

사용자, 팀, 트랜잭션 정책, 키를 만들고 제휴 ID로 트랜잭션에 서명하려면 다자간 계산 사용자 가이드를 따르세요. 각 사용자의 주 구성원을 제휴 ID를 v1beta 사용자로 추가에 설명된 principal:// 식별자로 설정합니다.
사용자 가이드는 애플리케이션 기본 사용자 인증 정보가 아닌 gcloud CLI 사용자 인증 정보를 사용하는 gcloud auth print-access-token를 통해 각 가상 인물의 액세스 토큰을 검색합니다. 3단계의 옵션 A에 표시된 대로 gcloud auth login --login-config를 사용하여 각 제휴 사용자를 로그인합니다.
보안 및 승인에서 사용자 역할, IAM 권한, 리소스 수준 조건에 대해 자세히 알아보세요.