Mengonfigurasi Workload Identity Federation dengan sertifikat X.509

Panduan ini menjelaskan cara menggunakan Workload Identity Federation dengan sertifikat X.509 yang diterbitkan oleh certificate authority (CA) Anda untuk melakukan autentikasi ke Google Cloud dan mengakses Google Cloud resource.

Jika workload Anda memiliki sertifikat klien mTLS, Anda dapat melakukan autentikasi ke Google Cloud dengan mendaftarkan satu atau beberapa CA ke Workload Identity Federation sebagai anchor kepercayaan. Anda juga dapat mendaftarkan CA perantara.

Dengan menggunakan Workload Identity Federation, Anda dapat mengizinkan workload ini mendapatkan kredensial Google Cloud dengan masa aktif singkat melalui koneksi mutual TLS (mTLS). Workload dapat menggunakan kredensial jangka pendek ini untuk mengakses Google Cloud API.

Konsep

Konsep federasi berbasis sertifikat X.509 mencakup hal berikut:

  • Anchor kepercayaan adalah sertifikat CA yang dianggap sebagai root kepercayaan. Semua rantai sertifikat klien harus dirantai hingga salah satu anchor kepercayaan.

  • CA perantara adalah sertifikat CA opsional yang membantu membangun rantai sertifikat klien.

  • Trust store berisi sertifikat trust anchor dan sertifikat CA perantara yang digunakan untuk memvalidasi rantai sertifikat klien. CA menerbitkan sertifikat tepercaya untuk klien.

    Anda dapat mengupload jenis sertifikat klien berikut ke trust store:

Sebelum memulai

Untuk mulai mengonfigurasi Workload Identity Federation, lakukan hal berikut:

  1. Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .

    Peran yang diperlukan untuk memilih atau membuat project

    • Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    Buka pemilih project

    2. Sebaiknya Anda menggunakan project khusus untuk mengelola workload identity pool dan penyedia workload.

  2. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

    3. Aktifkan IAM, Resource Manager, Service Account Credentials, dan Security Token Service API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengonfigurasi Workload Identity Federation, minta administrator Anda untuk memberi Anda peran IAM berikut pada project:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

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

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.

Membuat trust store

Bagian ini menunjukkan cara membuat trust store. Pada tingkat tinggi, langkah-langkahnya adalah sebagai berikut:

Membuat sertifikat yang ditandatangani sendiri

Bagian ini menunjukkan cara membuat kunci dan membuat sertifikat bertanda tangan. Jika sudah membuat sertifikat, Anda dapat melewati bagian ini dan melanjutkan ke Memformat sertifikat.

Bagian ini menggunakan perintah openssl untuk membuat sertifikat root dan sertifikat perantara.

Untuk membuat root certificate dan intermediate certificate bertanda tangan dengan kolom keyUsage dan extendedKeyUsage yang valid, lakukan langkah-langkah berikut:

  1. Buat file konfigurasi openssl untuk membuat sertifikat penandatanganan Anda. Setidaknya, file tersebut mirip dengan berikut ini, tetapi Anda dapat menetapkan kolom tambahan sesuai kebutuhan.

    cat > example.cnf << EOF
[req]
distinguished_name = empty_distinguished_name
[empty_distinguished_name]
# Kept empty to allow setting via -subj command-line argument.
[ca_exts]
basicConstraints=critical,CA:TRUE
keyUsage=keyCertSign
extendedKeyUsage=clientAuth
[leaf_exts]
keyUsage=critical,Digital Signature, Key Encipherment
basicConstraints=critical, CA:FALSE
EOF

  2. Buat sertifikat root.

    openssl req -x509 \
    -new -sha256 -newkey rsa:2048 -nodes \
    -days 3650 -subj '/CN=root' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout root.key -out root.cert

  3. Buat permintaan penandatanganan untuk sertifikat perantara.

    openssl req \
    -new -sha256 -newkey rsa:2048 -nodes \
    -subj '/CN=int' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout int.key -out int.req

  4. Buat intermediate certificate.

    openssl x509 -req \
    -CAkey root.key -CA root.cert \
    -set_serial 1 \
    -days 3650 \
    -extfile example.cnf \
    -extensions ca_exts \
    -in int.req -out int.cert

  5. Buat permintaan penandatanganan untuk sertifikat leaf.

    openssl req -new -sha256 -newkey rsa:2048 -nodes \
    -subj '/CN=example' \
    -config example.cnf \
    -extensions leaf_exts \
    -keyout leaf.key -out leaf.req

  6. Buat sertifikat leaf yang dikeluarkan oleh sertifikat perantara.

    openssl x509 -req \
    -CAkey int.key -CA int.cert \
    -set_serial 1 -days 3650 \
    -extfile example.cnf \
    -extensions leaf_exts \
    -in leaf.req -out leaf.cert

Memformat sertifikat

Untuk menyertakan sertifikat baru atau yang sudah ada dalam trust store, format sertifikat menjadi string satu baris, dan simpan dalam variabel lingkungan. Sertifikat harus diformat PEM. Untuk memformat sertifikat dan menyimpannya dalam variabel lingkungan, lakukan hal berikut:

  1. Simpan sertifikat root sebagai string satu baris.

    export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

  2. Simpan sertifikat perantara sebagai string satu baris.

    export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

Membuat trust store

Di bagian ini, Anda akan membuat trust store menggunakan file berformat YAML yang berisi anchor tepercaya dan CA perantara.

File ini berisi konten sertifikat dari variabel lingkungan yang Anda buat di Format sertifikat. Untuk menambahkan anchor tepercaya tambahan, tambahkan entri trustAnchors tambahan di bagian trustStore. Untuk menambahkan sertifikat CA perantara tambahan, tambahkan entri intermediateCas tambahan di bagian trustStore.

Untuk membuat file trust store, jalankan perintah berikut:

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Menentukan pemetaan dan kondisi atribut

Sertifikat X.509 klien dapat berisi beberapa atribut. Anda harus memilih atribut mana yang ingin digunakan sebagai ID subjek dengan memetakan google.subject in Google Cloud ke atribut dari sertifikat Anda. Misalnya, jika atribut dalam sertifikat adalah nama umum subjek, pemetaannya adalah sebagai berikut: google.subject=assertion.subject.dn.cn

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

Pemetaan atribut Anda dapat menggunakan atribut dalam sertifikat klien, termasuk berikut ini:

  • serialNumberHex: nomor seri
  • subject.dn.cn: nama umum subjek
  • subject.dn.o: nama organisasi subjek
  • subject.dn.ou: unit organisasi terakhir subjek
  • issuer.dn.cn: nama umum penerbit
  • issuer.dn.o: nama organisasi penerbit
  • issuer.dn.ou: unit organisasi terakhir penerbit
  • san.dns: nama DNS pertama dari nama alternatif subjek
  • san.uri: URI pertama nama alternatif subjek
  • sha256Fingerprint: Hash sertifikat leaf SHA256 (Base64)

Anda harus memetakan salah satu atribut ini ke google.subject untuk mengidentifikasi subjek secara unik. Untuk melindungi dari ancaman spoofing, pilih atribut dengan nilai unik yang tidak dapat diubah. Secara default, ID google.subject disetel ke nama umum subjek sertifikat klien, assertion.subject.dn.cn.

Secara opsional, Anda dapat menentukan kondisi atribut. Kondisi atribut adalah ekspresi CEL yang dapat memeriksa atribut pernyataan dan atribut target. Jika kondisi atribut dievaluasi ke true untuk kredensial tertentu, kredensial tersebut akan diterima. Jika tidak, kredensial akan ditolak.

Anda dapat menggunakan kondisi atribut untuk membatasi subjek yang dapat menggunakan Workload Identity Federation untuk mendapatkan token Google Cloud jangka pendek.

Misalnya, kondisi berikut membatasi akses ke sertifikat klien yang berisi SPIFFE ID spiffe://example/path:

assertion.san.uri=="spiffe://example/path"

Mengonfigurasi Workload Identity Federation

Bagian ini menunjukkan cara mengonfigurasi workload identity pool dan penyedia workload identity pool. Anda hanya perlu melakukan langkah-langkah ini satu kali untuk setiap penyimpanan tepercaya. Kemudian, Anda dapat menggunakan workload identity pool dan penyedia workload yang sama untuk beberapa workload dan di beberapa Google Cloud project.

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:

    • 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. Di bagian Tambahkan penyedia ke pool, lakukan hal berikut:

    1. Di Pilih penyedia, pilih X509.
    2. Pada Nama penyedia, masukkan nama penyedia. Nama ini juga digunakan sebagai ID penyedia. Anda tidak dapat mengubah ID penyedia setelah penyedia dibuat.
    3. Di Anchor tepercaya, masukkan sertifikat CA tepercaya Anda dalam format PEM. Sertifikat ini digunakan untuk memvalidasi rantai sertifikat klien.
    4. Opsional: Di Sertifikat perantara, masukkan sertifikat CA perantara dalam format PEM untuk membantu membangun rantai kepercayaan penuh.
    5. Klik Lanjutkan.

  5. Di bagian Konfigurasi atribut penyedia, tambahkan pemetaan dan kondisi atribut yang telah Anda identifikasi sebelumnya.

  6. Klik Simpan.

gcloud

  1. Untuk membuat workload identity pool baru, jalankan perintah berikut:

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

    Ganti kode berikut:

    • POOL_ID: ID unik untuk pool
    • DISPLAY_NAME: Nama pool
    • DESCRIPTION: Deskripsi pool yang Anda pilih Deskripsi ini muncul saat Anda memberikan akses ke identitas pool.

  2. Untuk menambahkan penyedia workload identity pool X.509, jalankan perintah berikut:

    gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
    --location=global \
    --workload-identity-pool="POOL_ID" \
    --trust-store-config-path="TRUST_STORE_CONFIG" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Ganti kode berikut:

    • PROVIDER_ID: ID penyedia unik untuk workload identity pool yang Anda pilih.
    • POOL_ID: ID workload identity pool yang telah Anda buat sebelumnya.
    • TRUST_STORE_CONFIG: File YAML trust store.
    • MAPPINGS: Daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda buat sebelumnya dalam dokumen ini. Misalnya, google.subject=assertion.subject.dn.cn.
    • CONDITIONS: Opsional. Kondisi atribut yang Anda buat sebelumnya dalam dokumen ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.

Mengonfigurasi Penerapan Kebijakan Akses Kontekstual untuk Workload Identity Federation

Anda dapat memperkuat keamanan resource terhadap serangan pemutaran ulang token dengan mengaktifkan Akses Kontekstual, yang menerapkan validasi mTLS untuk permintaan akses. Dalam proses ini, binding mTLS menggabungkan kebijakan berdasarkan konteks transport dan menggunakan status sertifikat klien dalam sesi TLS untuk membuat keputusan otorisasi. Untuk workload identity federation X.509, binding mTLS memastikan bahwa seluruh alur autentikasi terikat dengan aman ke beban kerja tepercaya. Hal ini mengurangi risiko pencurian kredensial, karena autentikasi terikat ke endpoint tertentu yang tepercaya.

Mengautentikasi workload

Langkah ini harus dilakukan satu kali untuk setiap workload.

Mengizinkan workload eksternal Anda mengakses resource Google Cloud

Untuk memberikan akses workload Anda ke resource Google Cloud , sebaiknya Anda memberikan akses resource langsung ke principal. Dalam hal ini, pokoknya 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 akun layanan. Dalam hal ini, akun utama adalah akun layanan Google Cloud , yang bertindak sebagai identitas. Anda memberikan akses ke akun layanan pada resource.

Akses resource langsung

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

Konsol

Untuk menggunakan konsol Google Cloud guna memberikan peran IAM langsung pada 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) kepada identitas gabungan langsung di bucket Cloud Storage.

  1. Di konsol Google Cloud , buka halaman Buckets Cloud Storage.

    Buka Buckets

  2. Dalam daftar bucket, klik nama bucket yang ingin Anda beri 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, administrator@example.com

    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: administrator-group@example.com

    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 Select a role. Peran yang Anda pilih akan muncul di panel dengan deskripsi singkat tentang izin yang diberikan.

  7. Klik Save.

gcloud

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

  1. Dapatkan nomor project tempat resource ditentukan.

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

  2. Beri 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 yang akan diberi akses
    • 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 khusus dalam pemetaan atribut Anda

    Anda dapat memberikan peran pada resource Google Cloud apa pun yang mendukung kebijakan izin IAM.

Peniruan akun layanan

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

    1. Aktifkan IAM, Security Token Service, dan Service Account Credentials API.

      Peran yang diperlukan untuk mengaktifkan API

      Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

      Aktifkan API

    2. Buat akun layanan yang merepresentasikan workload. Sebaiknya gunakan 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.

  2. Agar identitas gabungan dapat meniru identitas akun layanan, lakukan hal berikut:

Konsol

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

Akun Layanan dalam project yang sama

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

    1. Buka halaman Workload Identity Pool.

      Buka Workload Identity Pool

    2. Pilih Grant access.

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

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

    5. Untuk memilih identitas dalam pool 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 dalam project yang berbeda

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

    1. Buka halaman Akun Layanan.

      Buka Akun Layanan

    2. Pilih akun layanan yang ingin Anda tiru.

    3. Klik Kelola akses.

    4. Klik Add principal.

    5. Di kolom Principal baru, masukkan salah satu ID principal untuk identitas di pool 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, administrator@example.com

      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: administrator-group@example.com

      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 kumpulan

      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 memberikan peran Pengguna Workload Identity (roles/iam.workloadIdentityUser) kepada akun utama gabungan atau set akun utama, jalankan perintah berikut. Untuk mempelajari lebih lanjut ID utama Workload Identity Federation, lihat Jenis utama.

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 khusus dalam pemetaan atribut Anda

Mendownload atau membuat konfigurasi kredensial

Library Klien Cloud dan gcloud CLI dapat otomatis memperoleh kredensial eksternal dan menggunakan kredensial ini untuk meniru identitas akun layanan. Agar library dan alat dapat menyelesaikan proses ini, Anda harus menyediakan file konfigurasi kredensial.

Selain itu, untuk federasi sertifikat X.509, file konfigurasi sertifikat diperlukan.

File konfigurasi mencakup hal berikut:

  • Konfigurasi Kredensial: File JSON yang menentukan cara library klien berinteraksi dengan Security Token Service (STS).
  • Konfigurasi Sertifikat: File JSON yang menentukan jalur lokal untuk sertifikat klien dan kunci pribadi pada beban kerja Anda.

Buat file konfigurasi kredensial dan sertifikat yang memungkinkan library memperoleh token akses menggunakan sertifikat X.509.

Akses resource langsung

Untuk membuat file konfigurasi kredensial dan sertifikat untuk akses resource langsung, lakukan hal berikut:

Konsol

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

    Buka Workload Identity Pool

  2. Klik nama pool yang berisi penyedia yang ingin Anda gunakan.

  3. Klik Berikan akses.

  4. Di panel Grant access to service account, pilih Grant access using federated identities (Recommended).

  5. Klik Download config.

  6. Di bagian Konfigurasi aplikasi Anda, pilih penyedia yang berisi identitas eksternal dan berikan setelan berikut:

    • Jalur sertifikat klien: Jalur lokal ke file sertifikat klien Anda.
    • Jalur kunci pribadi klien: Jalur lokal ke file kunci pribadi klien Anda.
    • Jalur rantai kepercayaan: (Opsional) Jalur file rantai kepercayaan yang berisi sertifikat klien dan sertifikat perantara yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.

  7. Untuk mendownload arsip ZIP yang berisi file Konfigurasi Kredensial dan Konfigurasi Sertifikat, klik Download konfigurasi.

  8. Klik Tutup.

gcloud

  1. Untuk membuat file konfigurasi kredensial dan sertifikat untuk akses resource langsung menggunakan gcloud iam workload-identity-pools create-cred-config, jalankan perintah berikut:

    gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

    Ganti kode 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.
    • CLIENT_CERT_PATH: Jalur file sertifikat klien.
    • CLIENT_PRIVATE_KEY_PATH: Jalur file kunci pribadi sertifikat klien.
    • TRUST_CHAIN_PATH: Opsional. Jalur file rantai kepercayaan yang berisi sertifikat klien dan sertifikat perantara yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.
    • FILEPATH: File untuk menyimpan konfigurasi.

    Menjalankan perintah ini juga akan membuat file konfigurasi sertifikat dan menyimpannya di lokasi gcloud CLI default:

    • Linux dan macOS: ~/.config/gcloud/certificate_config.json

    • Windows: %APPDATA%\gcloud\certificate_config.json

Peniruan akun layanan

Untuk membuat file konfigurasi kredensial dan sertifikat dengan peniruan akun layanan, lakukan langkah-langkah berikut:

Konsol

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

    Buka Workload Identity Pool

  2. Klik nama pool yang berisi penyedia yang ingin Anda gunakan.

  3. Klik Berikan akses.

  4. Pilih Berikan akses menggunakan peniruan akun layanan.

  5. Pilih akun layanan yang ingin Anda tiru.

  6. Klik Download config.

  7. Dalam dialog Configure your application, berikan setelan berikut:

    • Jalur sertifikat klien: Jalur lokal ke file sertifikat klien Anda.
    • Jalur kunci pribadi klien: Jalur lokal ke file kunci pribadi klien Anda.
    • Jalur rantai kepercayaan: (Opsional) Jalur file rantai kepercayaan yang berisi sertifikat klien dan sertifikat perantara yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.

  8. Untuk mendownload arsip ZIP yang berisi file Konfigurasi Kredensial dan Konfigurasi Sertifikat, klik Download konfigurasi.

  9. Klik Tutup.

gcloud

  1. Untuk membuat file konfigurasi kredensial dan sertifikat dengan peniruan akun layanan menggunakan gcloud iam workload-identity-pools create-cred-config, jalankan perintah berikut:

    gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

    Ganti kode 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: Jika Anda menggunakan peniruan akun layanan, ganti SERVICE_ACCOUNT_EMAIL dengan alamat email akun layanan.
    • SERVICE_ACCOUNT_TOKEN_LIFETIME: Masa aktif token akses akun layanan, dalam detik, jika Anda menggunakan peniruan akun layanan. Jika dihilangkan, masa berlaku ini akan ditetapkan secara default ke satu jam. Hilangkan flag ini jika Anda tidak menggunakan peniruan akun layanan. Untuk menentukan masa aktif yang lebih lama dari satu jam, Anda harus mengonfigurasi constraints/iam.allowServiceAccountCredentialLifetimeExtension batasan kebijakan organisasi.
    • CLIENT_CERT_PATH: Jalur file sertifikat klien.
    • CLIENT_PRIVATE_KEY_PATH: Jalur file kunci pribadi sertifikat klien.
    • TRUST_CHAIN_PATH: Opsional. Jalur file rantai kepercayaan yang berisi sertifikat klien dan sertifikat perantara yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.
    • FILEPATH: File untuk menyimpan konfigurasi.

    Menjalankan perintah ini juga akan membuat file konfigurasi sertifikat dan menyimpannya di lokasi default Google Cloud CLI:

    • Linux dan macOS: ~/.config/gcloud/certificate_config.json

    • Windows: %APPDATA%\gcloud\certificate_config.json

Menggunakan konfigurasi kredensial untuk mengakses Google Cloud

Agar alat dan library klien dapat menggunakan konfigurasi kredensial Anda, lakukan hal berikut. Untuk mempelajari lebih lanjut Kredensial Default Aplikasi, lihat Cara kerja Kredensial Default Aplikasi.

  1. Jika Anda mendownload arsip ZIP dari konsol Google Cloud , ekstrak arsip di workload eksternal Anda.

  2. Perbarui file Certificate Configuration dengan jalur file lokal yang sebenarnya untuk sertifikat klien dan kunci pribadi Anda untuk kolom berikut:

    • cert_path: Jalur ke sertifikat klien Anda.
    • key_path: Jalur ke kunci pribadi Anda.

  3. Lakukan inisialisasi variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS dan tetapkan ke file konfigurasi kredensial:

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
    Ganti FILEPATH dengan jalur relatif ke file konfigurasi kredensial.

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
    Ganti FILEPATH dengan jalur relatif ke file konfigurasi kredensial.

  4. Pastikan library klien dapat menemukan file konfigurasi sertifikat. File konfigurasi sertifikat terletak di salah satu jalur berikut:

    • Jalur tempat Anda mengekstrak arsip ZIP. (jika Anda mendownload konfigurasi dari konsol Google Cloud ).

    • Jalur gcloud CLI default:

      • Linux dan macOS: ~/.config/gcloud/certificate_config.json

      • Windows: %APPDATA%\gcloud\certificate_config.json

    • Jalur yang ditetapkan dalam variabel lingkungan GOOGLE_API_CERTIFICATE_CONFIG.

  5. Gunakan Library Klien Cloud berikut yang mendukung Workload Identity Federation dengan sertifikat X.509.

    Go

    Library klien untuk Go mendukung X.509 Workload Identity Federation jika menggunakan modul cloud.google.com/go/auth versi 0.16.0 atau yang lebih baru dan modul google.golang.org/api versi 0.189.0.

    Untuk memeriksa versi modul yang digunakan library klien Anda, jalankan perintah berikut saat berada di direktori yang berisi file go.mod untuk modul Anda:

      go list -m cloud.google.com/go/auth
  go list -m cloud.google.com/api

    Python

    Library klien untuk Python mendukung X.509 Workload Identity Federation jika menggunakan paket google-auth versi 2.39.0 atau yang lebih baru.

    Untuk memeriksa versi paket yang digunakan library klien Anda, jalankan perintah berikut di lingkungan tempat paket diinstal:

      pip show google-auth

    Untuk menentukan project ID bagi klien autentikasi, Anda dapat menetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT atau mengizinkan klien untuk otomatis menemukan project ID. Untuk otomatis menemukan project ID, akun layanan dalam file konfigurasi harus memiliki peran Browser (roles/browser), atau peran dengan izin yang setara, di project Anda. Untuk mengetahui detailnya, lihat panduan pengguna untuk paket google-auth.

  6. Jika workload Anda berjalan di macOS, tetapkan CLOUDSDK_PYTHON_SITEPACKAGES=1 untuk mengonfigurasi gcloud CLI agar menggunakan library Python di luar direktori instalasinya.

  7. Untuk melakukan autentikasi menggunakan gcloud CLI, jalankan perintah berikut:

    gcloud auth login --cred-file=FILEPATH.json

    Ganti FILEPATH dengan jalur ke file konfigurasi kredensial.

    Dukungan untuk X.509 Workload Identity Federation di gcloud CLI tersedia di gcloud CLI versi 538.0 dan versi yang lebih baru.

Mendapatkan token akses menggunakan permintaan biasa untuk mengakses Google Cloud

Membuat rantai kepercayaan

Langkah ini menunjukkan cara membuat rantai kepercayaan. Anda meneruskan rantai kepercayaan di kolom subject_token saat memanggil Security Token Service dalam permintaan biasa.

Format sertifikat yang perlu disertakan dalam rantai sebagai daftar berformat JSON seperti yang ditentukan dalam RFC 7515. Sertifikat leaf yang digunakan untuk handshake mTLS harus ditentukan sebagai item pertama. Setiap sertifikat dalam paket harus berupa string berenkode base64.

  1. Simpan sertifikat leaf dan intermediate certificate ke string berenkode base64.

    export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)

    export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)

  2. Buat daftar string berformat JSON yang dapat diteruskan sebagai subject_token dalam panggilan ke Security Token Service, nanti dalam panduan ini.

    export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"

Mendapatkan token akses

Untuk mendapatkan token akses, lakukan hal berikut:

  1. Lakukan pertukaran token dengan mTLS dan sertifikat klien:

    curl --key CLIENT_CERT_KEY \
--cert CLIENT_CERT \
--request POST 'https://sts.mtls.googleapis.com/v1/token' \
--header "Content-Type: application/json" \
--data-raw '{
    "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "audience": "WORKLOAD_IDENTITY_POOL_URI",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "https://www.googleapis.com/auth/cloud-platform",
    "subject_token": "TRUST_CHAIN"
}'

    Ganti kode berikut:

    • CLIENT_CERT_KEY: Kunci pribadi sertifikat klien
    • CLIENT_CERT: Sertifikat klien

    • WORKLOAD_IDENTITY_POOL_URI: URL penyedia workload identity pool dalam format berikut:

      //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    • TRUST_CHAIN: Rantai kepercayaan yang diperlukan untuk memverifikasi sertifikat leaf, setidaknya harus menyertakan CLIENT_CERT sebagai item pertama. Jika Anda mengikuti petunjuk di bagian Format sertifikat, ganti TRUST_CHAIN dengan '"${TRUST_CHAIN}"'

  2. Opsional: Jika Anda menggunakan peniruan akun layanan, panggil metode generateAccessToken dari IAM Service Account Credentials API dengan token dari Security Token Service untuk mendapatkan token akses.

    curl -X POST 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken' \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer STS_TOKEN" \
    -d '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}'

    Ganti kode berikut:

    • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan.
    • STS_TOKEN: Token akses yang dibuat oleh Layanan Token Keamanan pada langkah sebelumnya.

  3. Gunakan token akses pembawa untuk mengakses resource Google Cloud , misalnya:

    curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"

Batas

Tabel berikut mencantumkan batas.

Item Batas Catatan
Jumlah anchor kepercayaan 3 Setiap sertifikat tidak boleh melebihi 32 KB.
Jumlah intermediate certificate 10 Setiap sertifikat tidak boleh melebihi 32 KB.
Jumlah batasan nama yang diizinkan selama validasi sertifikat root dan intermediate 10
Sertifikat perantara yang memiliki informasi Subjek dan Kunci Publik Subjek yang sama 5 Batas ini berlaku untuk setiap toko tepercaya.
Kedalaman rantai sertifikat 5 Kedalaman maksimum untuk rantai sertifikat, termasuk sertifikat root dan klien.
Jumlah kali sertifikat perantara dapat dievaluasi saat mencoba membangun rantai kepercayaan 100
Kunci sertifikat yang diupload dan diteruskan dari klien

Kunci RSA dapat berukuran 2048 hingga 4096 bit.

Sertifikat ECDSA harus menggunakan kurva P-256 atau P-384.

 RSA-2048 dan P-256 direkomendasikan untuk kasus penggunaan normal, gunakan yang lain untuk praktik keamanan terbaik.
Masa berlaku maksimum sertifikat entitas akhir 390 hari. Sertifikat dengan periode validitas lebih dari 390 hari akan berhenti berfungsi setelah valid selama lebih dari 390 hari.

Langkah berikutnya