Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengonfigurasi Workforce Identity Federation (BYOID)

Panduan ini menjelaskan cara mengonfigurasi Bring Your Own Identity (BYOID) untuk Multi-party Compute API menggunakan Workforce Identity Federation dan Workload Identity Federation. Dengan workforce identity federation, pengguna manusia dan workload penanda tangan otomatis dapat melakukan autentikasi ke Multi-party Compute menggunakan Penyedia Identitas (IdP) eksternal organisasi Anda, seperti Okta, Microsoft Entra ID, atau Ping Identity. Anda tidak perlu membuat Akun Google atau mengelola kunci akun layanan yang berumur panjang.

Ringkasan

Federasi identitas terintegrasi dengan model keamanan defense in depth Multi-party Compute di seluruh lapisan berikut:

Otorisasi Identity and Access Management (IAM) Edge: Pemanggil menukar kredensial dari IdP OpenID Connect (OIDC) atau SAML 2.0 eksternal dengan Google Cloud Security Token Service (Security Token Service) untuk mendapatkan token akses gabungan yang berumur singkat. Google Cloud Gateway API mengevaluasi binding peran IAM terhadap URI akun utama gabungan sebelum meneruskan permintaan ke instance Komputasi Multi-pihak, dan menyebarkan identitas gabungan (principalSubject) untuk Cloud Audit Logs.
Pemisahan tugas dan persetujuan kriptografis: Peran IAM memisahkan penyediaan administratif (roles/mpc.admin), partisipasi operasional (roles/mpc.editor), dan pengawasan hanya baca (roles/mpc.viewer). Dalam instance Anda, Admin, Penulis Kebijakan, dan Penanda Tangan juga memerlukan Pengguna yang perannya (ADMIN, POLICY_AUTHOR, atau SIGNER) diperiksa oleh instance untuk metode yang bertindak atas nama Pengguna, dan persetujuan harus ditandatangani dengan kunci otorisasi yang terdaftar pada Pengguna tersebut. Untuk mengetahui informasi selengkapnya, lihat Cara permintaan diizinkan.

Bergantung pada jenis pemanggil, Anda dapat menggunakan dua mekanisme workforce identity federation:

Workforce Identity Federation (locations/global/workforcePools/...): Mengautentikasi pengguna manusia (Administrator, Penulis Kebijakan, Penanda Tangan, dan Kepatuhan) menggunakan workforce pool tingkat organisasi yang dipetakan ke IdP perusahaan Anda. Panduan ini menjelaskan cara mengonfigurasi Workforce Identity Federation secara menyeluruh.
Workload Identity Federation (projects/.../locations/global/workloadIdentityPools/...): Mengautentikasi workload otomatis (seperti daemon co-signer headless yang berjalan di AWS, Azure, atau Kubernetes) menggunakan workload identity pool level project.

Untuk mengetahui informasi selengkapnya tentang cara peran IAM dipetakan ke persona Multi-party Compute, lihat Keamanan dan otorisasi.

Sebelum memulai

Sebelum memulai, pastikan Anda memiliki hal berikut:

Organisasi Google Cloud dan project konsumen yang diaktivasi ke Multi-party Compute.
gcloud CLI dan jq telah diinstal, dan gcloud diautentikasi dengan akun administratif yang memiliki peran berikut:
- Workforce Pool Admin (roles/iam.workforcePoolAdmin) di organisasi Google Cloud Anda (jika membuat workforce pool baru di Langkah 1).
- Project IAM Admin (roles/resourcemanager.projectIamAdmin) dan Service Usage Admin (roles/serviceusage.serviceUsageAdmin) di project konsumen Anda.

API yang diperlukan diaktifkan di project konsumen Anda:

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

Aplikasi OIDC atau SAML 2.0 eksternal yang dikonfigurasi di IdP perusahaan Anda. Jika Anda berencana menggunakan login browser interaktif dengan gcloud CLI, konfigurasikan URI pengalihan Google Cloud di aplikasi IdP Anda (lihat panduan penyiapan untuk Okta dan Microsoft Entra ID).

Penyiapan

Perbarui variabel berikut untuk mengisi perintah di seluruh panduan ini.

Parameter penyiapan yang diperlukan

Sesuaikan parameter ini agar sesuai dengan lingkungan dan konfigurasi IdP eksternal Anda Google Cloud .

Parameter	Nilai	Deskripsi
ID Organisasi	`123456789012`	ID organisasi Google Cloud numerik Anda.
Project ID	`my-project`	Project ID konsumen yang terdaftar untuk instance Multi-party Compute Anda.
ID Domain	`67317436-0f29-ba9e-9146-d11c0bd8df9b`	ID domain unik yang ditetapkan ke instance Multi-party Compute Anda.
ID Jalur Instance	`mpc-unit-bob-123`	ID jalur instance yang ditetapkan ke instance Multi-party Compute Anda.
Location	`us-central1`	Lokasi deployment (`us-central1`). Untuk mengetahui informasi selengkapnya, lihat Lokasi Komputasi Multi-pihak.
ID Workforce Pool	`mpc-workforce-pool`	ID workforce identity pool level organisasi.
ID Penyedia	`mpc-oidc-provider`	ID penyedia workforce identity pool.
URI Penerbit IdP	`https://idp.example.com`	URI penerbit IdP OIDC eksternal Anda.
Client ID IdP	`mpc-client`	Client ID OAuth 2.0 yang dikonfigurasi di IdP eksternal Anda.

Langkah 1: Konfigurasi workforce identity pool dan penyedia workforce identity

Workforce identity pool (locations/global/workforcePools/mpc-workforce-pool) adalah resource tingkat organisasi yang dipetakan ke tenant IdP perusahaan Anda. Anda tidak perlu membuat workforce pool terpisah untuk setiap project atau peran.

Buat workforce identity pool di organisasi Google Cloud Anda:

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

Buat penyedia workforce pool OIDC yang memercayai IdP eksternal Anda dan memetakan klaim subjek dan grup:
```
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"
```
Catatan: Secara default, Security Token Service menemukan dan merotasi kunci penandatanganan publik dari endpoint /.well-known/openid-configuration IdP Anda. Jika Anda melakukan pengujian dengan penerbit OIDC offline atau sintetis yang tidak dapat dijangkau secara publik, teruskan --jwk-json-path="<var>PATH_TO_JWK_FILE</var>", dengan mengganti <var>PATH_TO_JWK_FILE</var> dengan jalur lokal ke file JSON Web Key Set (JWKS) publik penerbit Anda. Untuk penyedia SAML 2.0, gunakan gcloud iam workforce-pools providers create-saml dengan --idp-metadata-path.

Langkah 2: Memberikan peran IAM ke akun utama gabungan

Untuk memanggil MPC API, akun utama gabungan memerlukan dua jenis binding peran IAM di project konsumen Anda (my-project):

Service Usage Consumer (roles/serviceusage.serviceUsageConsumer), yang memberi otorisasi kepada identitas gabungan untuk mengatribusikan kuota API dan penagihan ke project konsumen Anda.
Peran Multi-party Compute (roles/mpc.admin, roles/mpc.editor, atau roles/mpc.viewer), yang mengizinkan operasi Multi-party Compute tertentu.

Dalam produksi, ikat peran IAM ke grup IdP yang berbeda dalam workforce pool Anda:

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

Workload penanda tangan otomatis (Workload Identity Federation)

Jika Anda menjalankan daemon penanda tangan bersama otomatis di luar Google Cloud (misalnya, di AWS, Azure, atau Kubernetes), konfigurasikan workload identity pool dan penyedia yang tercakup dalam project. Berikan roles/serviceusage.serviceUsageConsumer dan roles/mpc.editor ke workload principal (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>, mengganti <var>PROJECT_NUMBER</var>, <var>WORKLOAD_POOL_ID</var>, dan <var>SIGNER_NODE_SUBJECT</var> dengan nomor project, ID workload pool, dan klaim sub workload Anda), dan buat file Kredensial Default Aplikasi menggunakan gcloud iam workload-identity-pools create-cred-config.

Menambahkan identitas gabungan sebagai Pengguna v1beta

Di v1beta API, peran IAM dari langkah ini memungkinkan identitas gabungan memanggil instance Anda. Untuk bertindak di dalam instance, sebagai Admin, Penulis Kebijakan, atau Penanda Tangan, identitas juga memerlukan Pengguna. Instance mengidentifikasi pemanggil dengan mencocokkan akun utama pemanggil dengan kolom principal dari setiap Pengguna.

Untuk identitas gabungan Workforce Identity Federation, tetapkan principal ke ID entitas subjek identitas:

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

Ganti SUBJECT_ID dengan nilai yang dipetakan penyedia Anda ke google.subject. Dengan pemetaan atribut di Langkah 1, ini adalah klaim sub dari token ID pengguna.

Saat Anda menetapkan principal, perhatikan hal berikut:

Gunakan ID principal://, bukan ID principalSet://. Pengguna adalah satu orang. ID grup dan pool seperti principalSet://.../group/mpc-signers berfungsi dalam binding peran IAM, tetapi tidak pernah cocok dengan pemanggil, sehingga Pengguna yang dibuat dengan ID tersebut tidak dapat bertindak dalam instance.
Cocokkan subjek sama persis. Instance ini membandingkan subjek workforce dan workload dengan peka huruf besar/kecil, jadi salin subjek seperti yang dikeluarkan oleh IdP Anda. Email Akun Google, seperti alice@example.com, dibandingkan tanpa membedakan huruf besar/kecil.
Anda tidak dapat mengubah principal nanti. Untuk mengubah identitas Pengguna, nonaktifkan Pengguna dan buat yang baru.

Langkah 3: Lakukan autentikasi dan dapatkan token akses gabungan

MPC API tidak menerima token OIDC atau pernyataan SAML langsung dari IdP Anda. Tukarkan kredensial IdP dengan Security Token Service untuk mendapatkan token akses Google Cloud gabungan sebelum memanggil endpoint instance Multi-party Compute (*.mpc.goog).

Anda dapat memperoleh dan mengelola token akses gabungan secara otomatis menggunakan Kredensial Default Aplikasi (ADC) dan gcloud CLI, atau secara terprogram menggunakan Security Token Service API.

Kredensial Default Aplikasi dan gcloud CLI

Dalam aplikasi klien produksi dan sesi CLI interaktif, gunakan file konfigurasi agar Google Cloud SDK dan Library Klien Cloud menangani pertukaran, caching, dan pemuatan ulang token Security Token Service di latar belakang secara otomatis.

Opsi A: Login browser interaktif

Buat file konfigurasi login dan autentikasi gcloud CLI dan Kredensial Default Aplikasi (ADC) dengan IdP perusahaan Anda:

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"

Opsi B: Login non-interaktif dengan file konfigurasi kredensial (ADC)

Jika proses eksternal menyediakan dan memperbarui token OIDC yang ditandatangani dalam file lokal (misalnya, /var/run/secrets/tokens/oidc-token) sebelum masa berlaku token berakhir, buat file konfigurasi kredensial eksternal:

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"

Ekspor token akses untuk permintaan curl:

Setelah menyelesaikan Opsi A atau Opsi B, ekspor token akses gabungan dari ADC ke ACCESS_TOKEN:

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

Pertukaran token STS REST langsung

Jika Anda mengintegrasikan klien kustom tanpa SDK Google Cloud , tukarkan token ID OIDC yang ditandatangani (<var>IDP_ID_TOKEN</var>) langsung dengan Security Token Service. Sertakan userProject di kolom options agar Google Cloud mengatribusikan token ke project konsumen Anda:

# 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 .

Langkah 4: Verifikasi akses API gabungan

Pastikan kredensial gabungan, atribusi userProject, dan binding peran IAM Anda berfungsi dengan mencantumkan Pengguna di instance Multi-party Compute Anda. Karena mpc.googleapis.com/users.list disertakan dalam roles/mpc.viewer, roles/mpc.editor, dan roles/mpc.admin, persona gabungan yang diizinkan dapat menjalankan pemeriksaan ini:

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 .

Respons JSON 200 OK (baik {} pada instance baru atau daftar users) mengonfirmasi bahwa identitas gabungan Anda diautentikasi dan diotorisasi untuk memanggil instance Multi-party Compute Anda.

Pemeriksaan ini hanya menggunakan IAM. Untuk mengonfirmasi bahwa instance juga mengenali identitas Anda sebagai Pengguna, pastikan salah satu Pengguna yang ditampilkan memiliki ID principal:// Anda di kolom principal-nya. Untuk mengetahui informasi selengkapnya, lihat Menambahkan identitas gabungan sebagai Pengguna v1beta.

Pemecahan masalah

Jika Anda mengalami error autentikasi atau izin saat memanggil Multi-party Compute dengan kredensial gabungan, verifikasi persyaratan berikut:

Atribusi project pengguna (`401 UNAUTHENTICATED: Unable to determine client project number`)

Penyebab: Kredensial workforce pool tingkat organisasi tidak terikat secara intrinsik ke satu project Google Cloud kecuali jika project pengguna ditentukan selama pertukaran token atau pada permintaan.
Penyelesaian: Sertakan options: {"userProject": "<var>PROJECT_ID</var>"} dalam isi permintaan pertukaran token Security Token Service (atau --workforce-pool-user-project di gcloud iam workforce-pools create-cred-config), dan sertakan header X-Goog-User-Project: <var>PROJECT_ID</var> pada panggilan API MPC Anda.

Izin Service Usage tidak ada (`403 PERMISSION_DENIED`)

Penyebab: Akun utama atau grup gabungan tidak memiliki izin untuk mengatribusikan penggunaan API ke project konsumen yang ditentukan di userProject atau X-Goog-User-Project.
Penyelesaian: Berikan roles/serviceusage.serviceUsageConsumer kepada anggota principal:// atau principalSet:// Anda di project konsumen (lihat Langkah 2).

Project konsumen tidak cocok (`403 PERMISSION_DENIED: Project is not allowed to call the API through this host`)

Penyebab: Setiap endpoint instance komputasi multi-party khusus hanya menerima permintaan dari project konsumen yang dikonfigurasi untuk instance tersebut.
Penyelesaian: Pastikan <var>PROJECT_ID</var> di jalur URL permintaan dan header userProject / X-Goog-User-Project cocok dengan project konsumen yang disediakan untuk instance komputasi Multi-party Compute Anda.

Kredensial tidak valid (`401 UNAUTHENTICATED: Request credential is invalid`)

Penyebab: Token OIDC atau pernyataan SAML pihak ketiga dikirim langsung ke endpoint Multi-party Compute tanpa ditukar terlebih dahulu menggunakan Security Token Service.
Penyelesaian: Tukarkan kredensial IdP Anda melalui https://sts.googleapis.com/v1/token (atau gunakan Kredensial Default Aplikasi) dan teruskan token akses Google Cloud yang dihasilkan di header Authorization: Bearer.

Kebijakan pembatasan domain memblokir binding peran (`400 FAILED_PRECONDITION`)

Penyebab: Organisasi Google Cloud Anda menerapkan kebijakan organisasi constraints/iam.allowedPolicyMemberDomains, yang membatasi domain akun utama yang dapat diberi peran IAM pada project.
Penyelesaian: Minta Administrator Kebijakan Organisasi Anda untuk menambahkan set akun utama workforce pool Anda ke domain anggota kebijakan yang diizinkan di project atau organisasi konsumen Anda, atau uji di project tempat constraints/iam.allowedPolicyMemberDomains mengizinkan workforce pool Anda.

Langkah berikutnya

Untuk membuat Pengguna, Tim, kebijakan transaksi, dan kunci, serta untuk menandatangani transaksi dengan identitas gabungan Anda, ikuti Panduan Pengguna Multi-party Compute. Tetapkan akun utama setiap Pengguna ke ID principal:// yang dijelaskan dalam Menambahkan identitas gabungan sebagai Pengguna v1beta.
Panduan pengguna mengambil token akses setiap persona dengan gcloud auth print-access-token, yang menggunakan kredensial CLI gcloud, bukan Kredensial Default Aplikasi. Login setiap pengguna gabungan dengan gcloud auth login --login-config, seperti yang ditunjukkan pada Opsi A di Langkah 3.
Pelajari lebih lanjut Peran pengguna, izin IAM, dan kondisi level resource di Keamanan dan otorisasi.