Mengonfigurasi Workload Identity Federation dengan pipeline deployment

Panduan ini menjelaskan cara menggunakan Workload Identity Federation agar pipeline deployment dapat melakukan autentikasi ke Google Cloud.

Tergantung pada sistem CI/CD yang Anda gunakan, pipeline deployment Anda mungkin memiliki akses ke kredensial khusus lingkungan sekitar. Contoh:

• Pipeline Azure DevOps dapat menggunakan koneksi layanan federasi identitas beban kerja Microsoft Entra untuk mendapatkan token ID yang mengidentifikasi project Azure DevOps secara unik.
• Alur kerja GitHub Actions dapat memperoleh token OIDC GitHub yang mengidentifikasi alur kerja dan repositorinya secara unik.
• GitLab SaaS memungkinkan tugas CI/CD mengakses token ID yang secara unik mengidentifikasi tugas beserta project, lingkungan, dan repositorinya.
• Terraform Cloud dapat menyediakan token OIDC untuk konfigurasi Terraform Anda yang secara unik mengidentifikasi ruang kerja dan lingkungannya.

Anda dapat mengonfigurasi pipeline deployment Anda agar dapat menggunakan kredensial ini untuk melakukan autentikasi ke Google Cloud menggunakan Workload Identity Federation. Pendekatan ini menghilangkan beban pemeliharaan dan keamanan yang terkait dengan kunci akun layanan.

Sebelum memulai

Menyiapkan autentikasi

Select the tab for how you plan to use the samples on this page:

Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Python

Untuk menggunakan contoh Python di halaman ini dalam lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi Workload Identity Federation, minta administrator untuk memberi Anda peran IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Atau, peran dasar Pemilik IAM (roles/owner) juga mencakup izin untuk mengonfigurasi penggabungan identitas. Anda tidak boleh memberikan peran dasar dalam lingkungan produksi, tetapi Anda dapat memberikannya dalam lingkungan pengembangan atau pengujian.

Menyiapkan IdP eksternal Anda

Azure DevOps

Agar pipeline Azure DevOps dapat diautentikasi ke Google Cloud, Anda harus mengonfigurasi koneksi layanan untuk Azure Resource Manager terlebih dahulu. Koneksi ini memungkinkan pipeline mendapatkan token ID, yang kemudian dapat ditukar dengan kredensial Google Cloud.

Untuk membuat koneksi layanan untuk Azure Resource Manager, lakukan langkah berikut:

1. Di Azure DevOps, buka project Anda dan buka Project Settings.
2. Buka Pipeline > Koneksi layanan.
3. Klik Create service connection.
4. Pilih Azure Resource Manager.
5. Klik Berikutnya.
6. Pilih Workload Identity federation (automatic)
7. Klik Berikutnya.

8. Konfigurasi setelan berikut:

   • Tingkat cakupan: Pilih langganan.

     Anda harus memilih langganan meskipun tidak berencana menggunakan koneksi layanan untuk mengakses resource Azure.

   • Nama koneksi layanan: Masukkan nama seperti google-cloud.

9. Klik Simpan.

Pada langkah selanjutnya, Anda memerlukan ID penerbit dan subjek koneksi layanan. Untuk mencari detail ini, lakukan langkah berikut:

1. Klik koneksi layanan yang baru saja Anda buat.
2. Klik Kelola Akun Layanan.
3. Buka Certificate & secrets > Federated credentials.
4. Klik kredensial gabungan.

5. Di halaman Edit kredensial, temukan ID berikut:

   • Issuer: mengidentifikasi organisasi Azure DevOps Anda secara unik
   • ID subjek: mengidentifikasi koneksi layanan secara unik

Azure DevOps otomatis memberikan akses pada langganan yang Anda pilih sebagai cakupan ke akun utama layanan yang terkait dengan koneksi layanan baru Anda. Karena Anda tidak berencana menggunakan koneksi layanan untuk mengakses resource Azure, Anda dapat mencabut akses ini dengan melakukan tindakan berikut:

1. Di portal Azure, buka langganan yang Anda pilih sebagai cakupan.
2. Buka Kontrol akses (IAM) > Penetapan peran.
3. Temukan penetapan peran untuk koneksi layanan dan hapus.

GitHub Actions

Anda tidak perlu membuat perubahan konfigurasi apa pun di akun GitHub Anda.

Setelah Anda mengonfigurasi workload identity pool agar dapat memercayai repositori GitHub Anda, Anda dapat mengizinkan alur kerja dalam repositori tersebut untuk menggunakan token OIDC GitHub-nya untuk mendapatkan kredensial Google Cloud dengan masa berlaku singkat.

GitLab SaaS

Anda tidak perlu membuat perubahan konfigurasi apa pun di akun GitLab Anda.

Setelah Anda mengonfigurasi workload identity pool agar memercayai grup GitLab Anda, Anda dapat mengaktifkan Workload Identity Federation untuk setiap tugas CI/CD.

Terraform Cloud

Anda tidak perlu membuat perubahan konfigurasi apa pun di akun Terraform Cloud.

Setelah Anda mengonfigurasi workload identity pool agar memercayai Terraform Cloud, Anda dapat mengaktifkan Workload Identity Federation untuk setiap ruang kerja.

Mengonfigurasi Workload Identity Federation

Anda harus melakukan langkah ini untuk setiap organisasi GitHub, grup GitLab, atau organisasi Terraform Cloud.

Untuk mulai mengonfigurasi Workload Identity Federation, lakukan langkah berikut:

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

Sebaiknya, gunakan project khusus untuk mengelola workload identity pool dan penyedia workload identity.

2. Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

Menentukan pemetaan atribut

Kredensial khusus lingkungan dari pipeline deployment Anda dapat berisi beberapa atribut, dan Anda harus menentukan atribut mana yang ingin Anda gunakan sebagai ID subjek (google.subject) di Google Cloud.

Secara opsional, Anda dapat memetakan atribut tambahan. Selanjutnya, Anda dapat merujuk ke atribut tambahan ini saat Anda memberikan akses ke resource.

Azure DevOps

Token ID Azure DevOps menyertakan klaim sub yang berisi ID subjek koneksi layanan Anda. ID subjek menggunakan format berikut:

sc://ORGANIZATION/PROJECT/CONNECTION

Gunakan pemetaan atribut berikut untuk memetakan ID ini ke google.subject:

google.subject=assertion.sub

GitHub Actions

Pemetaan atribut Anda dapat menggunakan salah satu klaim di token OIDC GitHub Actions. Kunci klaim token ini dan nilainya dikontrol oleh GitHub. Setidaknya, Anda harus memetakan google.subject ke assertion.sub, yang sesuai dengan subjek token OIDC GitHub Actions:

google.subject=assertion.sub

Nilai untuk subjek token OIDC GitHub Actions dapat bervariasi tergantung pada peristiwa sumber. Atribut klaim lainnya dapat mencakup:

• repository: Berisi nama pemilik dan repositori–contohnya "google/guava".

• repository_id: Berisi ID repositori unik–contohnya "20300177".

• repository_owner: Berisi pemilik, yang dapat berupa nama pengguna atau nama organisasi GitHub–contohnya "google".

• repository_owner_id: Berisi ID pemilik unik–contohnya "1342004".

Daftar ini adalah subset dari klaim yang memungkinkan–lihat dokumentasi GitHub tentang contoh klaim untuk mengetahui daftar lengkapnya. Pastikan untuk memetakan klaim apa pun yang akan Anda gunakan sebagai kondisi atribut atau sebagai bagian dari kondisi principalSet mendatang.

Penting: Menggunakan kolom "nama" seperti repository dan repository_owner akan meningkatkan peluang serangan cybersquatting dan typosquatting. Jika Anda menghapus repositori GitHub atau organisasi GitHub Anda, seseorang mungkin dapat mengklaim nama yang sama tersebut dan membuat identitas. Untuk melindungi dari situasi ini, gunakan kolom *_id numerik, yang unik dan tidak dapat digunakan kembali.

GitLab SaaS

Pemetaan atribut Anda dapat menggunakan klaim yang disematkan dalam token ID GitLab sebagai atribut sumber, termasuk berikut ini:

• sub: nama project dan referensi Git—contohnya, project_path:groupname/projectname:ref_type:branch:ref:main.
• namespace_id: ID grup unik.
• project_id: ID project unik.
• user_id: ID pengguna unik.
• environment: lingkungan tempat tugas diterapkan.
• ref_path: referensi Git—contohnya refs/heads/main.

Pemetaan atribut berikut menetapkan google.subject ke klaim sub dari token ID GitLab. Karena klaim sub berisi nama project dan referensi Git, pemetaan ini memungkinkan Anda mengontrol akses berdasarkan repositori dan cabang:

google.subject=assertion.sub

Mengontrol akses berdasarkan repositori dan cabang dapat berguna jika cabang tertentu (contohnya, main) memerlukan akses yang berbeda ke resource dibandingkan cabang lainnya (contohnya, cabang fitur).

Dalam beberapa kasus, Anda mungkin cukup membedakan akses berdasarkan project atau grup. Oleh karena itu, pemetaan berikut mencakup dua atribut tambahan yang berisi project_id dan namespace_id GitLab:

google.subject=assertion.sub
attribute.project_id=assertion.project_id
attribute.namespace_id=assertion.namespace_id

Terraform Cloud

Pemetaan atribut Anda dapat menggunakan klaim yang disematkan dalam token OIDC Terraform Cloud, termasuk klaim berikut

• terraform_organization_id: Berisi ID unik organisasi—contohnya org-xxxxxxxxxxxxxxxx.
• terraform_workspace_id: Berisi ID unik ruang kerja—contohnya ws-xxxxxxxxxxxxxxxx.
• terraform_workspace_name: Berisi nama tampilan ruang kerja.
• sub: Berisi nama tampilan organisasi, ruang kerja, dan fase—contohnya organization:example-org:workspace:example-workspace:run_phase:apply.

Pemetaan atribut berikut menetapkan google.subject ke klaim terraform_workspace_id dari token OIDC Terraform Cloud:

google.subject=assertion.terraform_workspace_id

Dengan pemetaan ini, Anda dapat mengontrol akses ke resource Google Cloud berdasarkan ruang kerja.

Menentukan kondisi atribut

Kondisi atribut adalah ekspresi CEL yang dapat memeriksa atribut pernyataan dan atribut target. Jika kondisi atribut bernilai true untuk kredensial tertentu, kredensial tersebut akan diterima. Jika tidak, kredensial akan ditolak. Anda harus memiliki pemetaan atribut untuk semua kolom kondisi atribut.

Peringatan: GitHub, GitLab SaaS, dan Terraform Cloud menggunakan satu URL penerbit di semua organisasi dan beberapa klaim yang disematkan dalam token OIDC mungkin tidak unik untuk organisasi Anda. Untuk membantu melindungi dari ancaman spoofing, Anda harus menggunakan kondisi atribut yang membatasi akses ke token yang dikeluarkan oleh organisasi GitHub, grup GitLab, atau organisasi Terraform Cloud Anda.

Azure DevOps

Secara opsional, gunakan kondisi atribut untuk membatasi akses ke koneksi layanan tertentu. Misalnya, kondisi berikut membatasi akses ke koneksi dalam project Azure DevOps tertentu:

assertion.sub.startsWith('sc://ORGANIZATION/PROJECT/')

Ganti kode berikut:

• ORGANIZATION: nama organisasi Azure DevOps Anda.
• PROJECT: nama project Azure DevOps Anda.

GitHub Actions

Gunakan kondisi atribut berikut untuk membatasi akses ke token yang dikeluarkan oleh organisasi GitHub Anda:

assertion.repository_owner=='ORGANIZATION'

Ganti ORGANIZATION dengan nama organisasi GitHub Anda.

Secara opsional, perluas kondisi atribut untuk membatasi akses ke subset alur kerja atau cabang. Contohnya, kondisi berikut membatasi akses ke alur kerja yang menggunakan main cabang Git:

assertion.repository_owner=='ORGANIZATION' && assertion.ref=='refs/heads/main'

GitLab SaaS

Gunakan kondisi atribut berikut untuk membatasi akses ke token yang dikeluarkan oleh grup GitLab Anda

assertion.namespace_id=='GROUP_ID'

Ganti GROUP_ID dengan ID grup yang ditampilkan di halaman beranda grup GitLab Anda.

Secara opsional, perluas kondisi atribut untuk membatasi akses ke subset project, cabang, atau lingkungan. Contohnya, kondisi berikut membatasi akses ke tugas yang menggunakan production lingkungan:

assertion.namespace_id=='GROUP_ID' && assertion.environment=='production'

Terraform Cloud

Gunakan kondisi atribut berikut untuk membatasi akses ke token yang dikeluarkan oleh organisasi Terraform Cloud Anda:

assertion.terraform_organization_id=='ORGANIZATION_ID'

Ganti ORGANIZATION_ID dengan ID unik organisasi Anda—contohnya org-xxxxxxxxxxxxxxxx. Secara opsional, perluas kondisi atribut untuk membatasi akses ke subset alur kerja atau cabang. Contohnya, kondisi atribut berikut membatasi akses ke ruang kerja tertentu:

assertion.terraform_organization_id=='ORGANIZATION_ID' && assertion.terraform_workspace_id=='WORKSPACE_ID'

Membuat workload identity pool dan penyedia workload

Anda telah mengumpulkan semua informasi yang Anda perlukan untuk membuat workload identity pool dan penyedia workload:

Konsol

1. Di konsol Google Cloud, buka halaman Penyedia workload dan workload pool baru .

   Buka Penyedia workload dan workload pool baru

2. Di bagian Buat identity pool, masukkan informasi berikut:

   • Nama: Nama untuk pool. Nama ini juga digunakan sebagai ID pool. Anda tidak dapat mengubah ID pool nanti.
   • Deskripsi: Teks yang menjelaskan tujuan pool.

3. Klik Lanjutkan.

4. Konfigurasikan setelan penyedia:

   Azure DevOps

   • Pilih penyedia: OpenID Connect (OIDC).
   • Nama penyedia: nama project Azure DevOps, atau nama kustom.
   • ID Penyedia: nama project Azure DevOps, atau ID kustom. Anda tidak dapat mengubah ID penyedia nantinya.
   • Issuer URL: penerbit koneksi layanan yang telah Anda cari sebelumnya.

   • Audiens: Pilih Audiens yang diizinkan dan tempelkan nilai berikut

     api://AzureADTokenExchange
     

   GitHub Actions

   • Pilih penyedia: OpenID Connect (OIDC).
   • Nama penyedia: Nama untuk penyedia.
   • ID Penyedia: ID untuk penyedia. Anda tidak dapat mengubah ID penyedia nantinya.
   • URL Penerbit: https://token.actions.githubusercontent.com/
   • Audiens: Audiens default

   GitLab SaaS

   • Pilih penyedia: OpenID Connect (OIDC).
   • Nama penyedia: Nama untuk penyedia.
   • ID Penyedia: ID untuk penyedia. Anda tidak dapat mengubah ID penyedia nantinya.
   • URL Penerbit: https://gitlab.com
   • Audiens: Audiens default

   Terraform Cloud

   • Pilih penyedia: OpenID Connect (OIDC).
   • Nama penyedia: Nama untuk penyedia.
   • ID Penyedia: ID untuk penyedia. Anda tidak dapat mengubah ID penyedia nantinya.
   • URL Penerbit: https://app.terraform.io
   • Audiens: Audiens default

5. Klik Lanjutkan.

6. Di bagian Konfiguraasikan atribut penyedia, tambahkan pemetaan atribut yang telah Anda identifikasi sebelumnya.

7. Di bagian Kondisi atribut, masukkan kondisi atribut yang telah Anda identifikasi sebelumnya.

8. Klik Simpan untuk membuat workload identity pool dan penyedia workload.

gcloud

1. Buat workload identity pool baru:

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Ganti nilai berikut:

   • POOL_ID: ID unik untuk pool
   • DISPLAY_NAME: nama pool
   • DESCRIPTION: deskripsi pool. Deskripsi ini muncul saat memberikan akses ke identitas kumpulan

2. Tambahkan penyedia workload identity pool:

   Azure DevOps

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="ISSUER" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Ganti nilai berikut:

   • PROVIDER_ID: nama project Azure DevOps, atau ID kustom untuk penyedia.
   • POOL_ID: ID pool
   • ISSUER: penerbit koneksi layanan yang telah Anda cari sebelumnya.
   • MAPPINGS: daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda identifikasi sebelumnya
   • CONDITIONS: kondisi atribut yang Anda identifikasi sebelumnya

   GitHub Actions

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://token.actions.githubusercontent.com/" \
       --allowed-audiences="api://AzureADTokenExchange" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Ganti nilai berikut:

   • PROVIDER_ID: ID unik untuk penyedia
   • POOL_ID: ID pool
   • MAPPINGS: daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda identifikasi sebelumnya
   • CONDITIONS: kondisi atribut yang Anda identifikasi sebelumnya

   GitLab SaaS

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://gitlab.com" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Ganti nilai berikut:

   • PROVIDER_ID: ID unik untuk penyedia
   • POOL_ID: ID pool
   • MAPPINGS: daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda identifikasi sebelumnya
   • CONDITIONS: kondisi atribut yang Anda identifikasi sebelumnya

   Terraform Cloud

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://app.terraform.io" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Ganti nilai berikut:

   • PROVIDER_ID: ID unik untuk penyedia.
   • POOL_ID: ID pool.
   • MAPPINGS: daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda identifikasi sebelumnya.
   • CONDITIONS: kondisi atribut yang telah Anda identifikasi sebelumnya.

Catatan: Awalan gcp- dicadangkan dan tidak dapat digunakan di ID pool atau ID penyedia.

Memperbarui kondisi atribut di penyedia workload identity

Bagian ini menjelaskan cara memperbarui kondisi atribut di penyedia workload identity pool yang ada untuk membatasi akses ke token yang dikeluarkan oleh organisasi GitHub, grup GitLab, atau organisasi Terraform Cloud Anda.

Untuk menemukan kondisi atribut yang direkomendasikan untuk pipeline Anda, lihat Menentukan kondisi atribut.

Konsol

1. Di konsol Google Cloud, buka halaman Workload Identity Pool.

   Buka Workload Identity Pool

2. Temukan workload identity pool yang berisi penyedia, lalu klik ikon Luaskan node untuk pool.

3. Temukan penyedia workload identity pool yang ingin Anda edit, lalu klik Edit.

4. Di Kondisi atribut, masukkan kondisi atribut yang telah Anda identifikasi sebelumnya.

5. Untuk memperbarui workload identity pool dan penyedia, klik Simpan.

gcloud

Untuk memperbarui penyedia workload identity pool, jalankan perintah berikut:

gcloud iam workload-identity-pools providers update-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --attribute-condition="CONDITIONS"

Ganti nilai berikut:

• PROVIDER_ID: ID unik untuk penyedia
• POOL_ID: ID pool
• CONDITIONS: kondisi atribut yang telah Anda identifikasi sebelumnya

Mengautentikasi pipeline deployment

Anda harus melakukan langkah ini untuk setiap alur kerja GitHub Actions atau ruang kerja Terraform Cloud.

Mengizinkan workload eksternal Anda mengakses resource Google Cloud

Untuk menyelesaikan petunjuk nanti dalam panduan ini, Anda harus mengonfigurasi peniruan identitas akun layanan seperti yang dijelaskan di bagian ini.

Untuk memberi beban kerja Anda akses ke resource Google Cloud, sebaiknya Anda memberikan akses resource langsung ke akun utama. Dalam hal ini, prinsipal adalah pengguna gabungan. Beberapa produk Google Cloud memiliki batasan Google Cloud API. Jika beban kerja Anda memanggil endpoint API yang memiliki batasan, Anda dapat menggunakan peniruan identitas akun layanan. Dalam hal ini, akun utama adalah akun layanan Google Cloud, yang bertindak sebagai identitas. Anda memberikan akses ke akun layanan di resource.

Akses resource langsung

Anda dapat memberikan akses ke identitas gabungan langsung di resource menggunakan konsol Google Cloud atau gcloud CLI.

Konsol

Untuk menggunakan konsol Google Cloud guna memberikan peran IAM langsung di resource, Anda harus membuka halaman resource, lalu memberikan peran. Contoh berikut menunjukkan cara membuka halaman Cloud Storage dan memberikan peran Storage Object Viewer (roles/storage.objectViewer) ke identitas gabungan langsung di bucket Cloud Storage.

1. Di Konsol Google Cloud, buka halaman Bucket Cloud Storage.
   

   Buka Bucket

2. Pada daftar bucket, klik nama bucket tempat Anda ingin memberi peran.

3. Pilih tab Permissions di dekat bagian atas halaman.

4. Klik tombol Berikan akses.

   Dialog Add principals akan muncul.

5. Di kolom Akun utama baru, masukkan satu atau beberapa identitas yang memerlukan akses ke bucket Anda.

   Menurut subjek

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

   Ganti kode berikut:

   • PROJECT_NUMBER: nomor project
   • POOL_ID: ID workload pool
   • SUBJECT: subjek individu yang dipetakan dari IdP Anda—misalnya, [e-mail]

   Menurut grup

   principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
   

   Ganti kode berikut:

   • PROJECT_NUMBER: nomor project
   • WORKLOAD_POOL_ID: ID workload pool
   • GROUP: grup yang dipetakan dari IdP Anda—misalnya: [e-mail]

   Menurut atribut

   principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
   

   Ganti kode berikut:

   • PROJECT_NUMBER: nomor project
   • WORKLOAD_POOL_ID: ID workload pool
   • ATTRIBUTE_NAME: salah satu atribut yang dipetakan dari IdP Anda
   • ATTRIBUTE_VALUE: nilai atribut

6. Pilih satu (atau beberapa) peran dari menu drop-down Pilih peran. Peran yang Anda pilih akan muncul di panel dengan deskripsi singkat tentang izin yang diberikan.

7. Klik Simpan.

gcloud

Untuk menggunakan gcloud CLI guna memberikan peran IAM pada resource dalam project, lakukan tindakan berikut:

1. Dapatkan nomor project dari project tempat resource ditentukan.

   gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
   

2. Berikan akses ke resource.

   Untuk menggunakan gcloud CLI guna memberikan peran Storage Object Viewer (roles/storage.objectViewer) kepada identitas eksternal yang memenuhi kriteria tertentu, jalankan perintah berikut.

   Menurut subjek

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

   Menurut grup

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

   Menurut atribut

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

   Ganti kode berikut:

   • BUCKET_ID: bucket tempat akses akan diberikan
   • PROJECT_NUMBER: nomor project dari project yang berisi workload identity pool
   • POOL_ID: ID pool dari workload identity pool
   • SUBJECT: nilai yang diharapkan untuk atribut yang Anda petakan ke google.subject
   • GROUP: nilai yang diharapkan untuk atribut yang Anda petakan ke google.groups
   • ATTRIBUTE_NAME: nama atribut khusus dalam pemetaan atribut Anda
   • ATTRIBUTE_VALUE: nilai atribut kustom dalam pemetaan atribut Anda

   Anda dapat memberikan peran di resource Google Cloud mana pun yang mendukung kebijakan izin IAM.

   Catatan: Anda harus menggunakan nomor project, bukan project ID, di ID anggota.

Peniruan akun layanan

1. Untuk membuat akun layanan bagi beban kerja eksternal, lakukan langkah-langkah berikut:

   1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

      Enable the APIs

   2. Buat akun layanan yang merepresentasikan workload. Sebaiknya Anda menggunakan akun layanan khusus untuk setiap workload. Akun layanan tidak perlu berada dalam project yang sama dengan workload identity pool, tetapi Anda harus merujuk ke project yang berisi akun layanan.

   3. Berikan akses akun layanan untuk resource yang ingin diakses oleh identitas eksternal.

   4. Berikan peran Workload Identity User (roles/iam.workloadIdentityUser) ke akun layanan.

2. Untuk memberikan akses ke identitas gabungan menggunakan peniruan identitas akun layanan menggunakan Konsol Google Cloud atau gcloud CLI:

Konsol

Untuk menggunakan konsol Google Cloud guna memberikan peran IAM ke identitas gabungan dengan akun layanan, lakukan tindakan berikut:

Akun Layanan dalam project yang sama

1. Untuk memberikan akses menggunakan peniruan identitas akun layanan untuk akun layanan di project yang sama, lakukan hal berikut:

   1. Buka halaman Workload Identity Pool.

      Buka Workload Identity Pool

   2. Pilih Berikan akses.

   3. Pada dialog Grant access to service account, pilih Grant access using Service Account impersonation.

   4. Dalam daftar Akun layanan, pilih akun layanan untuk ditiru oleh identitas eksternal, lalu lakukan hal berikut:

   5. Untuk memilih identitas dalam kumpulan yang dapat meniru identitas akun layanan, lakukan salah satu tindakan berikut:

      • Untuk mengizinkan hanya identitas tertentu dari workload identity pool untuk meniru identitas akun layanan, pilih Hanya identitas yang cocok dengan filter.

      • Di daftar Nama atribut, pilih atribut yang ingin Anda filter.

      • Di kolom Nilai atribut, masukkan nilai atribut yang diharapkan; misalnya, jika Anda menggunakan pemetaan atribut google.subject=assertion.sub, tetapkan nama Atribut menjadi subject dan Nilai atribut menjadi nilai klaim sub dalam token yang dikeluarkan oleh penyedia identitas eksternal Anda.

   6. Untuk menyimpan konfigurasi, klik Simpan, lalu Tutup.

Akun layanan di project lain

Catatan: Akun layanan dari project yang berbeda tidak akan muncul di bagian "CONNECTED SERVICE ACCOUNTS" di Workload Identity Pool Anda.

1. Untuk memberikan akses menggunakan peniruan akun layanan untuk akun layanan di project lain, lakukan hal berikut:

   1. Buka halaman Akun Layanan.

      Buka Akun Layanan

   2. Pilih akun layanan yang ingin Anda tirukan identitasnya.

   3. Klik Kelola akses.

   4. Klik Tambahkan akun utama.

   5. Di kolom New principal, masukkan salah satu ID akun utama berikut untuk identitas dalam kumpulan Anda yang akan meniru identitas akun layanan.

      Menurut subjek

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

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • POOL_ID: ID workload pool
      • SUBJECT: subjek individu yang dipetakan dari IdP Anda—misalnya, [e-mail]

      Menurut grup

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • WORKLOAD_POOL_ID: ID workload pool
      • GROUP: grup yang dipetakan dari IdP Anda—misalnya: [e-mail]

      Menurut atribut

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • WORKLOAD_POOL_ID: ID workload pool
      • ATTRIBUTE_NAME: salah satu atribut yang dipetakan dari IdP Anda
      • ATTRIBUTE_VALUE: nilai atribut

      Menurut kolam renang

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • WORKLOAD_POOL_ID: ID workload pool

   6. Di Select a role, pilih peran Workload Identity User (roles/iam.workloadIdentityUser).

   7. Untuk menyimpan konfigurasi, klik Simpan.

gcloud

Untuk menggunakan gcloud CLI guna memberikan peran Pemilik Workload Identity (roles/iam.workloadIdentityUser) ke identitas eksternal yang memenuhi kriteria tertentu, jalankan perintah berikut.

Menurut subjek

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

Menurut grup

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

Menurut atribut

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Ganti kode berikut:

• SERVICE_ACCOUNT_EMAIL: alamat email akun layanan
• PROJECT_NUMBER: nomor project dari project yang berisi workload identity pool
• POOL_ID: ID pool dari workload identity pool
• SUBJECT: nilai yang diharapkan untuk atribut yang Anda petakan ke google.subject
• GROUP: nilai yang diharapkan untuk atribut yang Anda petakan ke google.groups
• ATTRIBUTE_NAME: nama atribut khusus dalam pemetaan atribut Anda
• ATTRIBUTE_VALUE: nilai atribut kustom dalam pemetaan atribut Anda

Catatan: Anda harus menggunakan nomor project, bukan project ID, di ID anggota.

Mengonfigurasi pipeline deployment

Bagian ini menjelaskan cara menggunakan Workload Identity Federation di pipeline deployment Anda. Petunjuk di bagian ini mengasumsikan bahwa beban kerja Anda menggunakan peniruan identitas akun layanan untuk mengakses resource Google Cloud.

Azure DevOps

Edit file azure-pipelines.yml Anda dan tambahkan kode berikut ke konfigurasi tugas:

variables:
- name: Azure.WorkloadIdentity.Connection
  value: CONNECTION
- name: GoogleCloud.WorkloadIdentity.ProjectNumber
  value: PROJECT_NUMBER
- name: GoogleCloud.WorkloadIdentity.Pool
  value: POOL_ID
- name: GoogleCloud.WorkloadIdentity.Provider
  value: PROVIDER_ID
- name: GoogleCloud.WorkloadIdentity.ServiceAccount
  value: SERVICE_ACCOUNT_EMAIL
- name: GOOGLE_APPLICATION_CREDENTIALS
  value: $(Pipeline.Workspace)/.workload_identity.wlconfig

steps:
  - task: AzureCLI@2
    inputs:
      connectedServiceNameARM: $(Azure.WorkloadIdentity.Connection)
      addSpnToEnvironment: true
      scriptType: 'bash'
      scriptLocation: 'inlineScript'
      inlineScript: |
        echo $idToken > $(Pipeline.Workspace)/.workload_identity.jwt
        cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
        {
          "type": "external_account",
          "audience": "//iam.googleapis.com/projects/$(GoogleCloud.WorkloadIdentity.ProjectNumber)/locations/global/workloadIdentityPools/$(GoogleCloud.WorkloadIdentity.Pool)/providers/$(GoogleCloud.WorkloadIdentity.Provider)",
          "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
          "token_url": "https://sts.googleapis.com/v1/token",
          "credential_source": {
            "file": "$(Pipeline.Workspace)/.workload_identity.jwt"
          },
          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$(GoogleCloud.WorkloadIdentity.ServiceAccount):generateAccessToken"
        }
        EOF

Ganti nilai berikut:

• CONNECTION: nama koneksi layanan Anda
• PROJECT_NUMBER: nomor project dari project yang berisi workload identity pool
• POOL_ID: ID workload identity pool
• PROVIDER_ID: ID penyedia workload identity pool
• SERVICE_ACCOUNT_EMAIL: alamat email akun layanan

Konfigurasi tersebut akan melakukan hal berikut:

1. Menggunakan tugas AzureCLI untuk mendapatkan token ID untuk koneksi layanan, dan menyediakannya dalam variabel bernama idToken.
2. Menyimpan token ID ke file sementara yang bernama .workload_identity.jwt.
3. Membuat file konfigurasi kredensial yang menginstruksikan library klien untuk membaca token ID dari .workload_identity.jwt dan menggunakannya untuk meniru identitas akun layanan.
4. Menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS agar mengarah ke file konfigurasi kredensial.

GitHub Actions

Tindakan google-github-actions/auth memungkinkan Anda secara otomatis membuat file konfigurasi kredensial selama eksekusi alur kerja. Alat dan library klien seperti terraform dapat kemudian menggunakan file konfigurasi kredensial ini untuk secara otomatis mendapatkan kredensial Google.

Edit file YAML GitHub Actions Anda dan tambahkan hal berikut ini:

• Izinkan tugas untuk mengambil token ID GitHub dengan menambahkan konfigurasi berikut:

  permissions:
    id-token: write
    contents: read
  

• Tambahkan langkah untuk membuat file konfigurasi kredensial:

  - id: 'auth'
    name: 'Authenticate to Google Cloud'
    uses: 'google-github-actions/auth@v1'
    with:
      create_credentials_file: true
      workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
      service_account: 'SERVICE_ACCOUNT_EMAIL'
  

Ganti nilai berikut:

• PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool.
• POOL_ID: ID workload identity pool.
• PROVIDER_ID: ID penyedia workload identity pool.
• SERVICE_ACCOUNT_EMAIL: Ganti dengan alamat email akun layanan.

Contoh berikut mengonfigurasi GitHub Action:

jobs:
  build:
    # Allow the job to fetch a GitHub ID token
    permissions:
      id-token: write
      contents: read

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v1'
        with:
          create_credentials_file: true
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'

Untuk mengetahui detail lebih lanjut tentang penggunaan tindakan google-github-actions/auth, lihat Menyiapkan Workload Identity Federation.

GitLab SaaS

Edit file .gitlab-ci.yml Anda dan tambahkan kode berikut ke konfigurasi tugas:

job:
  variables:
    WORKLOAD_IDENTITY_PROJECT_NUMBER: PROJECT_NUMBER
    WORKLOAD_IDENTITY_POOL: POOL_ID
    WORKLOAD_IDENTITY_PROVIDER: PROVIDER_ID
    SERVICE_ACCOUNT: SERVICE_ACCOUNT_EMAIL
    GOOGLE_APPLICATION_CREDENTIALS: $CI_BUILDS_DIR/.workload_identity.wlconfig

  id_tokens:
    WORKLOAD_IDENTITY_TOKEN:
      aud: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

  script:
    - |-
      echo $WORKLOAD_IDENTITY_TOKEN > $CI_BUILDS_DIR/.workload_identity.jwt
      cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/projects/$WORKLOAD_IDENTITY_PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_IDENTITY_POOL/providers/$WORKLOAD_IDENTITY_PROVIDER",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "$CI_BUILDS_DIR/.workload_identity.jwt"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SERVICE_ACCOUNT:generateAccessToken"
      }
      EOF

Ganti nilai berikut:

• PROJECT_NUMBER: nomor project dari project yang berisi workload identity pool
• POOL_ID: ID workload identity pool
• PROVIDER_ID: ID penyedia workload identity pool
• SERVICE_ACCOUNT_EMAIL: alamat email akun layanan

Konfigurasi tersebut akan melakukan hal berikut:

1. Memberi petunjuk kepada GitLab untuk mengeluarkan token ID, dan menyediakannya di variabel lingkungan bernama WORKLOAD_IDENTITY_TOKEN. Token ID menggunakan penyedia workload identity pool Anda sebagai audiens.
2. Menyimpan token ID ke file sementara yang bernama .workload_identity.jwt.
3. Membuat file konfigurasi kredensial yang menginstruksikan library klien untuk membaca token ID dari .workload_identity.jwt dan menggunakannya untuk meniru identitas akun layanan.
4. Menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS agar mengarah ke file konfigurasi kredensial.

Terraform Cloud

Konfigurasikan ruang kerja Terraform Cloud Anda agar menggunakan Workload Identity Federation untuk melakukan autentikasi ke Google Cloud menggunakan peniruan identitas akun layanan:

1. Di Terraform Cloud, buka ruang kerja Anda, lalu buka Variabel.

2. Tambahkan variabel berikut:

   Kategori variabel	Kunci	Nilai
   Variabel lingkungan	TFC_GCP_PROVIDER_AUTH	true
   Variabel lingkungan	TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL	Alamat email akun layanan, contohnya [e-mail]
   Variabel lingkungan	TFC_GCP_PROJECT_NUMBER	Nomor project dari project yang berisi workload identity pool
   Variabel lingkungan	TFC_GCP_WORKLOAD_POOL_ID	ID workload identity pool
   Variabel lingkungan	TFC_GCP_WORKLOAD_PROVIDER_ID	ID penyedia workload identity pool

   Secara opsional, Anda dapat menambahkan variabel lingkungan tambahan untuk mengizinkan Terrform Cloud menggunakan akun layanan yang berbeda untuk fase plan dan apply. Untuk mengetahui informasi selengkapnya, lihat Variabel Lingkungan Opsional.

3. Dalam daftar variabel, pastikan Kategori ditetapkan menjadi env untuk lima variabel yang Anda tambahkan di langkah sebelumnya.

4. Pastikan konfigurasi Terraform Anda menggunakan penyedia Google Cloud versi 4.48.0 atau yang terbaru, dan perbarui jika perlu, seperti berikut:

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = "~> 4.48.0"
       }
     }
   }
   

5. Kirim perubahan ke repositori kode sumber Anda.

Langkah selanjutnya

• Baca selengkapnya tentang Workload Identity Federation.
• Pelajari praktik terbaik untuk menggunakan Workload Identity Federation dalam pipeline deployment.
• Lihat cara mengelola workload identity pool dan penyedia workload identity.

Kirim masukan